Skip to main content

syncular_client/
values.rs

1//! Value conversions at the client's edges: driver JSON (`{"$bytes": hex}`
2//! convention) ↔ the §2.4 row-codec values ↔ SQLite storage, plus the §11.2
3//! canonical scope JSON (contractual across implementations).
4
5use std::collections::HashMap;
6
7use serde_json::{Map, Value};
8use ssp2::primitives::{RawJson, Reader, Writer};
9use ssp2::segment::{
10    decode_row, encode_row, encode_sparse_row, Column, ColumnType, ColumnValue, Row, SparseRow,
11    SparseSlot,
12};
13
14use crate::schema::TableSchema;
15use crate::TransportError;
16
17/// §5.11 client-side encryption keys (`keyId → 32-byte key`) plus optional
18/// key selection. Empty ⇒ E2EE off. `key_id_for` defaults to per-table
19/// (`keyId = table`). Always present on the client; the crypto is compiled
20/// only under the `e2ee` feature.
21#[derive(Clone, Default)]
22pub struct EncryptionConfig {
23    pub keys: HashMap<String, Vec<u8>>,
24    /// Portable per-table selector: the named non-encrypted string column in
25    /// each plaintext row contains the key id used for new envelopes.
26    pub key_id_columns: HashMap<String, String>,
27}
28
29/// §5.11 sealed state of a delivered row: the `keyId` of its first
30/// undecryptable envelope (`_sync_sealed_key`) and its encrypted envelopes as
31/// a JSON object of column name to hex envelope (`_sync_sealed`).
32#[derive(Clone, Debug, PartialEq, Eq)]
33pub struct SealedRow {
34    pub key_id: String,
35    pub envelopes: String,
36}
37
38/// Manual Debug so a stray `{config:?}` log line stays free of key material:
39/// key entries render as `id → <N bytes>`.
40impl std::fmt::Debug for EncryptionConfig {
41    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
42        struct Redacted(usize);
43        impl std::fmt::Debug for Redacted {
44            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45                write!(f, "<{} bytes>", self.0)
46            }
47        }
48        let keys: std::collections::BTreeMap<&String, Redacted> = self
49            .keys
50            .iter()
51            .map(|(id, key)| (id, Redacted(key.len())))
52            .collect();
53        f.debug_struct("EncryptionConfig")
54            .field("keys", &keys)
55            .field("key_id_columns", &self.key_id_columns)
56            .finish()
57    }
58}
59
60impl Drop for EncryptionConfig {
61    fn drop(&mut self) {
62        // Best-effort native key hygiene: replacement, preflight entry, and
63        // client shutdown overwrite every owned key buffer before release.
64        for key in self.keys.values_mut() {
65            key.fill(0);
66        }
67    }
68}
69
70impl EncryptionConfig {
71    pub fn is_empty(&self) -> bool {
72        self.keys.is_empty()
73    }
74
75    /// §5.11 portable key selection: configured row column, then table name.
76    /// Encode-seam failures carry `client.encrypt_failed` (never the apply-
77    /// seam `client.decrypt_failed`). The caller supplies the presence set
78    /// first with the stored local row merged into an absent selector.
79    pub fn key_id_for(&self, table: &TableSchema, row: &Row) -> Result<String, String> {
80        let Some(column_name) = self.key_id_columns.get(&table.name) else {
81            return Ok(table.name.clone());
82        };
83        let Some(index) = table
84            .columns
85            .iter()
86            .position(|column| &column.name == column_name)
87        else {
88            return Err(format!(
89                "client.encrypt_failed: encryption key-id column {column_name:?} is not present on table {:?}",
90                table.name
91            ));
92        };
93        if table
94            .encrypted_columns
95            .iter()
96            .any(|column| column.index == index)
97        {
98            return Err(format!(
99                "client.encrypt_failed: encryption key-id column {column_name:?} on table {:?} must not be encrypted",
100                table.name
101            ));
102        }
103        match row.get(index).and_then(|value| value.as_ref()) {
104            Some(ColumnValue::String(key_id)) if !key_id.is_empty() => Ok(key_id.clone()),
105            _ => Err(format!(
106                "client.encrypt_failed: encryption key-id column {column_name:?} on table {:?} must contain a non-empty string",
107                table.name
108            )),
109        }
110    }
111}
112
113/// The pinned snake→camel conversion. The Rust
114/// copy of the typegen/TS-client algorithm, kept in lockstep by shared test
115/// vectors. Leading/trailing `_` runs are preserved; middle segments split
116/// on `_` (doubled underscores drop); no acronym awareness.
117pub fn snake_to_camel(name: &str) -> String {
118    let is_mappable = {
119        let bare = name.trim_start_matches('_');
120        !bare.is_empty()
121            && bare.chars().next().is_some_and(|c| c.is_ascii_alphabetic())
122            && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
123    };
124    if !is_mappable {
125        return name.to_owned();
126    }
127    let lead_len = name.len() - name.trim_start_matches('_').len();
128    let (lead, bare) = name.split_at(lead_len);
129    let trail_len = bare.len() - bare.trim_end_matches('_').len();
130    let (middle, trail) = bare.split_at(bare.len() - trail_len);
131    let mut segments = middle.split('_').filter(|s| !s.is_empty());
132    let Some(first) = segments.next() else {
133        return name.to_owned();
134    };
135    let mut out = String::with_capacity(name.len());
136    out.push_str(lead);
137    out.push_str(first);
138    for segment in segments {
139        let mut chars = segment.chars();
140        if let Some(head) = chars.next() {
141            out.push(head.to_ascii_uppercase());
142            out.push_str(chars.as_str());
143        }
144    }
145    out.push_str(trail);
146    out
147}
148
149/// §5 mutate key normalization: accept BOTH casings for upsert value keys —
150/// the SQL-truth snake_case and the generated row types' camelCase. A camel
151/// key renames to its column's SQL name when that is unambiguous (the alias
152/// equals no other column's exact name, and no two columns share it). A
153/// column given in both casings is an error. Unknown keys fail loud, matching
154/// the TypeScript core; silently dropping an app field would corrupt a
155/// full-row mutation while appearing successful.
156pub fn normalize_values_casing(
157    table: &TableSchema,
158    mut values: Map<String, Value>,
159) -> Result<Map<String, Value>, String> {
160    for column in &table.columns {
161        let camel = snake_to_camel(&column.name);
162        if camel == column.name {
163            continue;
164        }
165        // Exact names always win; an alias colliding with another column's
166        // real name (or with another column's alias) is not an alias.
167        if table.columns.iter().any(|c| c.name == camel) {
168            continue;
169        }
170        if table
171            .columns
172            .iter()
173            .filter(|c| snake_to_camel(&c.name) == camel)
174            .count()
175            > 1
176        {
177            continue;
178        }
179        if let Some(value) = values.remove(&camel) {
180            if values.contains_key(&column.name) {
181                return Err(format!(
182                    "sync.invalid_request: table {:?}: column {:?} appears twice in mutation values (as both snake_case and camelCase) — pass it once",
183                    table.name, column.name
184                ));
185            }
186            values.insert(column.name.clone(), value);
187        }
188    }
189    for key in values.keys() {
190        let Some(index) = table.columns.iter().position(|column| column.name == *key) else {
191            if key.starts_with("_sync_") {
192                return Err(format!(
193                    "sync.invalid_request: table {:?}: {:?} is an internal sync column and cannot appear in mutation values",
194                    table.name, key
195                ));
196            }
197            return Err(format!(
198                "sync.invalid_request: table {:?}: unknown column {:?} in mutation values (snake_case and camelCase keys are accepted)",
199                table.name, key
200            ));
201        };
202        if table.server_owned_columns.contains(&index) {
203            return Err(format!(
204                "sync.invalid_request: table {:?}: a server-owned column is not a mutation value (§6.7): {:?}",
205                table.name, key
206            ));
207        }
208    }
209    Ok(values)
210}
211
212pub fn bytes_to_hex(bytes: &[u8]) -> String {
213    let mut out = String::with_capacity(bytes.len() * 2);
214    for b in bytes {
215        out.push(char::from(b"0123456789abcdef"[usize::from(b >> 4)]));
216        out.push(char::from(b"0123456789abcdef"[usize::from(b & 15)]));
217    }
218    out
219}
220
221pub fn hex_to_bytes(hex: &str) -> Result<Vec<u8>, String> {
222    if !hex.len().is_multiple_of(2) {
223        return Err("odd-length hex string".to_owned());
224    }
225    let mut out = Vec::with_capacity(hex.len() / 2);
226    let nibble = |byte| match byte {
227        b'0'..=b'9' => byte - b'0',
228        b'a'..=b'f' => byte - b'a' + 10,
229        b'A'..=b'F' => byte - b'A' + 10,
230        _ => u8::MAX,
231    };
232    for pair in hex.as_bytes().as_chunks::<2>().0 {
233        // Preserve the prior radix parser's accepted +digit pair as well as
234        // uppercase input. Canonical encoders continue to emit lowercase hex.
235        let high = if pair[0] == b'+' { 0 } else { nibble(pair[0]) };
236        let low = nibble(pair[1]);
237        if high == u8::MAX || low == u8::MAX {
238            return Err(if std::str::from_utf8(pair).is_err() {
239                "non-ASCII hex".to_owned()
240            } else {
241                "bad hex: invalid digit found in string".to_owned()
242            });
243        }
244        out.push((high << 4) | low);
245    }
246    Ok(out)
247}
248
249/// Driver JSON value → row-codec value for one column. `null`/absent maps to
250/// NULL; bytes travel as `{"$bytes": "<hex>"}`.
251pub fn json_to_column_value(
252    column: &Column,
253    value: Option<&Value>,
254) -> Result<Option<ColumnValue>, String> {
255    let value = match value {
256        None | Some(Value::Null) => return Ok(None),
257        Some(v) => v,
258    };
259    let fail = |expected: &str| {
260        Err(format!(
261            "column {:?}: expected {expected}, got {value}",
262            column.name
263        ))
264    };
265    match column.ty {
266        ColumnType::String => match value.as_str() {
267            Some(s) => Ok(Some(ColumnValue::String(s.to_owned()))),
268            None => fail("a string"),
269        },
270        ColumnType::Integer => match value.as_i64() {
271            Some(i)
272                if (-ssp2::primitives::I64_SAFE_MAX..=ssp2::primitives::I64_SAFE_MAX)
273                    .contains(&i) =>
274            {
275                Ok(Some(ColumnValue::Integer(i)))
276            }
277            _ => fail("an integer within the JavaScript safe-integer range"),
278        },
279        ColumnType::Float => match value.as_f64() {
280            Some(f) => Ok(Some(ColumnValue::Float(f))),
281            None => fail("a number"),
282        },
283        ColumnType::Boolean => match value.as_bool() {
284            Some(b) => Ok(Some(ColumnValue::Boolean(b))),
285            None => fail("a boolean"),
286        },
287        // `json` columns stay raw strings at the driver boundary (§2.4).
288        ColumnType::Json => match value.as_str() {
289            Some(s) => Ok(Some(ColumnValue::Json(RawJson(s.to_owned())))),
290            None => fail("a raw JSON string"),
291        },
292        // `blob_ref` (tag 7) also stays a raw string at the boundary (§5.9.1).
293        ColumnType::BlobRef => match value.as_str() {
294            Some(s) => Ok(Some(ColumnValue::BlobRef(RawJson(s.to_owned())))),
295            None => fail("a raw BlobRef JSON string"),
296        },
297        ColumnType::Bytes => match value.get("$bytes").and_then(Value::as_str) {
298            Some(hex) => Ok(Some(ColumnValue::Bytes(hex_to_bytes(hex)?))),
299            None => fail("a {\"$bytes\": hex} object"),
300        },
301        // §5.10: crdt bytes cross the boundary as {"$bytes": hex}, like bytes.
302        ColumnType::Crdt => match value.get("$bytes").and_then(Value::as_str) {
303            Some(hex) => Ok(Some(ColumnValue::Crdt(hex_to_bytes(hex)?))),
304            None => fail("a {\"$bytes\": hex} object"),
305        },
306    }
307}
308
309/// Row-codec value → driver JSON value.
310pub fn column_value_to_json(value: &Option<ColumnValue>) -> Value {
311    match value {
312        None => Value::Null,
313        Some(ColumnValue::String(s)) => Value::from(s.clone()),
314        Some(ColumnValue::Integer(i)) => Value::from(*i),
315        Some(ColumnValue::Float(f)) => {
316            serde_json::Number::from_f64(*f).map_or(Value::Null, Value::Number)
317        }
318        Some(ColumnValue::Boolean(b)) => Value::from(*b),
319        Some(ColumnValue::Json(raw)) => Value::from(raw.0.clone()),
320        Some(ColumnValue::BlobRef(raw)) => Value::from(raw.0.clone()),
321        Some(ColumnValue::Bytes(bytes)) => {
322            let mut map = Map::new();
323            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(bytes)));
324            Value::Object(map)
325        }
326        Some(ColumnValue::Crdt(bytes)) => {
327            let mut map = Map::new();
328            map.insert("$bytes".to_owned(), Value::from(bytes_to_hex(bytes)));
329            Value::Object(map)
330        }
331    }
332}
333
334/// Turn an app-facing value map into a full-row map: every column present,
335/// a missing nullable column filled with NULL, a missing non-nullable column
336/// a loud error (§6.1 full-row payloads, §6.7 `mutate` marks every column).
337pub fn full_row_values(
338    table: &TableSchema,
339    mut values: Map<String, Value>,
340) -> Result<Map<String, Value>, String> {
341    for column in &table.columns {
342        if values.contains_key(&column.name) {
343            continue;
344        }
345        if !column.nullable {
346            return Err(format!(
347                "sync.invalid_request: table {:?}: column {:?} is not nullable (§6.1 full-row payloads)",
348                table.name, column.name
349            ));
350        }
351        values.insert(column.name.clone(), Value::Null);
352    }
353    Ok(values)
354}
355
356/// §7.1: exactly one `$bytes` key holding an even-length hexadecimal string.
357/// Uppercase digits are accepted; encoders emit lowercase.
358pub(crate) fn is_canonical_bytes_envelope(value: &Value) -> bool {
359    value
360        .as_object()
361        .filter(|map| map.len() == 1)
362        .and_then(|map| map.get("$bytes"))
363        .and_then(Value::as_str)
364        .is_some_and(|hex| {
365            hex.len().is_multiple_of(2) && hex.bytes().all(|byte| byte.is_ascii_hexdigit())
366        })
367}
368
369/// §7.1: a `bytes`/`crdt` column crosses the authoring boundary only as exactly
370/// one `$bytes` key holding an even-length hexadecimal string. The shared
371/// decoder keeps its tolerance for persisted payloads (§7.4.4 replay), so the
372/// canonical rule is enforced at the encode seams instead. `None` for every
373/// other column type and for a canonical envelope.
374fn author_bytes_envelope_error(column: &Column, value: &Value) -> Option<String> {
375    // An explicit `null` stays with `json_to_column_value`: a nullable column
376    // accepts it and a non-nullable one is classified by the required-column
377    // check, not by the envelope rule.
378    if value.is_null() || !matches!(column.ty, ColumnType::Bytes | ColumnType::Crdt) {
379        return None;
380    }
381    if is_canonical_bytes_envelope(value) {
382        return None;
383    }
384    Some(format!(
385        "sync.invalid_request: column {:?}: expected exactly {{\"$bytes\": hex}} with an even number of hexadecimal digits, got {value}",
386        column.name
387    ))
388}
389
390/// Encode one full row (driver JSON values keyed by column name) with the
391/// generated row codec (§2.4, §6.1). §5.11: encrypted columns are encrypted
392/// here — the encode-at-send seam — before the codec serializes them as
393/// ciphertext-envelope `bytes` using `wire_columns`.
394pub fn encode_row_json(
395    table: &TableSchema,
396    row_id: &str,
397    values: &Map<String, Value>,
398    encryption: &EncryptionConfig,
399) -> Result<Vec<u8>, String> {
400    // Build the row from the LOCAL (declared-type) columns.
401    let mut row: Row = Vec::with_capacity(table.columns.len());
402    for column in &table.columns {
403        if let Some(raw) = values.get(&column.name) {
404            if let Some(error) = author_bytes_envelope_error(column, raw) {
405                return Err(error);
406            }
407        }
408        // §6.1/§7.1: a caller value the codec rejects is an invalid request,
409        // never an internal authoring failure; the dynamic cause stays in
410        // `details.legacyCause` at the `ClientError` boundary.
411        let value = json_to_column_value(column, values.get(&column.name))
412            .map_err(|error| format!("sync.invalid_request: {error}"))?;
413        if value.is_none() && !column.nullable {
414            return Err(format!(
415                "sync.invalid_request: table {:?}: column {:?} is not nullable (§6.1 full-row payloads)",
416                table.name, column.name
417            ));
418        }
419        row.push(value);
420    }
421    if table.has_encrypted_columns() {
422        encrypt_row(table, row_id, &mut row, encryption)?;
423    }
424    // Serialize with the WIRE columns (encrypted columns are `bytes`).
425    let mut w = Writer::new();
426    encode_row(&mut w, &table.wire_columns, &row);
427    Ok(w.into_bytes())
428}
429
430/// Encode one SPARSE push payload (§2.4, §6.1): the keys of `values` ARE the
431/// presence set — a column with no key stays absent. §5.11: only present
432/// encrypted columns are encrypted, and key resolution runs only then;
433/// absent selector slots fall back to `fallback` (the stored local row).
434/// Serialized with the `wire_columns` table.
435pub fn encode_sparse_row_json(
436    table: &TableSchema,
437    row_id: &str,
438    values: &Map<String, Value>,
439    encryption: &EncryptionConfig,
440    fallback: Option<&Row>,
441) -> Result<Vec<u8>, String> {
442    let mut row: SparseRow = Vec::with_capacity(table.columns.len());
443    for column in &table.columns {
444        let Some(raw) = values.get(&column.name) else {
445            row.push(SparseSlot::Absent);
446            continue;
447        };
448        if let Some(error) = author_bytes_envelope_error(column, raw) {
449            return Err(error);
450        }
451        // §2.4/§7.1: the push admission values the server rejects. A float
452        // read from JSON is always finite.
453        let refused = match (column.ty, raw) {
454            (ColumnType::String, Value::String(text)) => text.contains('\0'),
455            (ColumnType::Json, Value::String(text)) => {
456                ssp2::primitives::parse_json_document(text, "json value").is_err()
457            }
458            (ColumnType::BlobRef, Value::String(text)) => {
459                ssp2::blob_ref::validate_blob_ref(text).is_err()
460            }
461            _ => false,
462        };
463        if refused {
464            return Err(format!(
465                "sync.invalid_request: column {:?}: the value is not a push admission value (§2.4)",
466                column.name
467            ));
468        }
469        let value = json_to_column_value(column, Some(raw))
470            .map_err(|error| format!("sync.invalid_request: {error}"))?;
471        if value.is_none() && !column.nullable {
472            return Err(format!(
473                "sync.invalid_request: table {:?}: column {:?} is not nullable (§6.1)",
474                table.name, column.name
475            ));
476        }
477        row.push(value.map_or(SparseSlot::Null, SparseSlot::Value));
478    }
479    if table.has_encrypted_columns() {
480        encrypt_sparse_row(table, row_id, &mut row, encryption, fallback)?;
481    }
482    Ok(encode_sparse_row(&table.wire_columns, table.pk_index, &row))
483}
484
485/// Decode one row-codec payload; trailing bytes are a decode error. §5.11:
486/// encrypted columns are decrypted here — the apply seam — back to their
487/// declared-type plaintext value for the local mirror, or the row lands
488/// sealed under a key the keyring lacks.
489pub fn decode_row_bytes(
490    table: &TableSchema,
491    payload: &[u8],
492    encryption: &EncryptionConfig,
493) -> Result<(Row, Option<SealedRow>), TransportError> {
494    let mut r = Reader::new(payload);
495    // Decode with the WIRE columns (encrypted columns arrive as `bytes`).
496    let mut row = decode_row(&mut r, &table.wire_columns)
497        .map_err(|e| TransportError::new("sync.invalid_request", e.to_string()))?;
498    if !r.is_empty() {
499        return Err(TransportError::new(
500            "sync.invalid_request",
501            "row payload has trailing bytes",
502        ));
503    }
504    let sealed = if table.has_encrypted_columns() {
505        decrypt_row(table, &mut row, encryption)?
506    } else {
507        None
508    };
509    Ok((row, sealed))
510}
511
512/// §5.11: decrypt the encrypted columns of an already-decoded segment row
513/// (rows segments decode via their own column table, so decryption is a
514/// post-decode pass over the positional values).
515pub fn decrypt_segment_row(
516    table: &TableSchema,
517    row: &mut Row,
518    encryption: &EncryptionConfig,
519) -> Result<Option<SealedRow>, TransportError> {
520    decrypt_row(table, row, encryption)
521}
522
523// -- §5.11 encrypt/decrypt seam (feature-gated) ------------------------------
524
525#[cfg(feature = "e2ee")]
526fn encrypt_row(
527    table: &TableSchema,
528    _row_id: &str,
529    row: &mut Row,
530    encryption: &EncryptionConfig,
531) -> Result<(), String> {
532    use rand_core::RngCore;
533    use ssp2::crypto::{encrypt_value, NONCE_LENGTH};
534    for enc in &table.encrypted_columns {
535        let Some(value) = row.get(enc.index).and_then(|v| v.as_ref()) else {
536            continue; // NULL stays NULL (§5.11)
537        };
538        let plain = column_value_to_plain(value)?;
539        let key_id = encryption.key_id_for(table, row)?;
540        let key = encryption
541            .keys
542            .get(&key_id)
543            .ok_or_else(|| format!("client.encrypt_failed: no key for keyId {key_id:?}"))?;
544        let mut nonce = [0u8; NONCE_LENGTH];
545        rand_core::OsRng.fill_bytes(&mut nonce);
546        let envelope = encrypt_value(&plain, &key_id, key, nonce)?;
547        row[enc.index] = Some(ColumnValue::Bytes(envelope));
548    }
549    Ok(())
550}
551
552#[cfg(feature = "e2ee")]
553fn encrypt_sparse_row(
554    table: &TableSchema,
555    _row_id: &str,
556    row: &mut SparseRow,
557    encryption: &EncryptionConfig,
558    fallback: Option<&Row>,
559) -> Result<(), String> {
560    use rand_core::RngCore;
561    use ssp2::crypto::{encrypt_value, NONCE_LENGTH};
562    // Sparse semantics: absent and NULL columns are never re-encrypted, so
563    // a patch presenting no encrypted value needs no key (§5.11).
564    let has_present_encrypted = table
565        .encrypted_columns
566        .iter()
567        .any(|enc| matches!(row.get(enc.index), Some(SparseSlot::Value(_))));
568    if !has_present_encrypted {
569        return Ok(());
570    }
571    // Densify absent columns to NULL for key-id selection only; an absent
572    // selector falls back to the stored local row. Absent ≠ NULL (§6.1):
573    // only an ABSENT slot reads the fallback, a present NULL never does.
574    let mut dense: Row = row
575        .iter()
576        .map(|slot| match slot {
577            SparseSlot::Value(value) => Some(value.clone()),
578            _ => None,
579        })
580        .collect();
581    if let Some(selector) = encryption.key_id_columns.get(&table.name) {
582        if let Some(index) = table
583            .columns
584            .iter()
585            .position(|column| &column.name == selector)
586        {
587            if matches!(row.get(index), None | Some(SparseSlot::Absent)) {
588                let stored: Option<&str> = match fallback
589                    .and_then(|row| row.get(index))
590                    .and_then(|value| value.as_ref())
591                {
592                    Some(ColumnValue::String(key_id)) => Some(key_id),
593                    _ => None,
594                };
595                if let Some(key_id) = stored.filter(|key_id| !key_id.is_empty()) {
596                    dense[index] = Some(ColumnValue::String(key_id.to_owned()));
597                }
598            }
599        }
600    }
601    let key_id = encryption.key_id_for(table, &dense)?;
602    for enc in &table.encrypted_columns {
603        let Some(SparseSlot::Value(value)) = row.get(enc.index) else {
604            continue; // absent or NULL stays untouched (§5.11)
605        };
606        let plain = column_value_to_plain(value)?;
607        let key = encryption
608            .keys
609            .get(&key_id)
610            .ok_or_else(|| format!("client.encrypt_failed: no key for keyId {key_id:?}"))?;
611        let mut nonce = [0u8; NONCE_LENGTH];
612        rand_core::OsRng.fill_bytes(&mut nonce);
613        let envelope = encrypt_value(&plain, &key_id, key, nonce)?;
614        row[enc.index] = SparseSlot::Value(ColumnValue::Bytes(envelope));
615    }
616    Ok(())
617}
618
619#[cfg(not(feature = "e2ee"))]
620fn encrypt_sparse_row(
621    table: &TableSchema,
622    _row_id: &str,
623    row: &mut SparseRow,
624    _encryption: &EncryptionConfig,
625    _fallback: Option<&Row>,
626) -> Result<(), String> {
627    if !table
628        .encrypted_columns
629        .iter()
630        .any(|enc| matches!(row.get(enc.index), Some(SparseSlot::Value(_))))
631    {
632        return Ok(());
633    }
634    Err(format!(
635        "table {:?} has encrypted columns but this build lacks the e2ee feature (§5.11)",
636        table.name
637    ))
638}
639
640/// §5.11 apply seam: under an unknown `keyId` the row comes back sealed:
641/// every encrypted column NULL plus its [`SealedRow`]. Every other failure is
642/// `client.decrypt_failed`.
643#[cfg(feature = "e2ee")]
644fn decrypt_row(
645    table: &TableSchema,
646    row: &mut Row,
647    encryption: &EncryptionConfig,
648) -> Result<Option<SealedRow>, TransportError> {
649    use ssp2::crypto::{decrypt_value, DeclaredType, DecryptValueError};
650    let failed = |message: String| TransportError::new("client.decrypt_failed", message);
651    let mut missing = None;
652    let mut envelopes = Map::new();
653    for enc in &table.encrypted_columns {
654        let Some(value) = row.get(enc.index).and_then(|v| v.as_ref()) else {
655            continue;
656        };
657        let ColumnValue::Bytes(envelope) = value else {
658            return Err(failed(format!(
659                "encrypted column at index {} is not bytes",
660                enc.index
661            )));
662        };
663        let declared = DeclaredType::from_name(&enc.declared_type)
664            .ok_or_else(|| failed(format!("unknown declaredType {:?}", enc.declared_type)))?;
665        envelopes.insert(
666            table.columns[enc.index].name.clone(),
667            Value::from(bytes_to_hex(envelope)),
668        );
669        let keys = &encryption.keys;
670        match decrypt_value(declared, envelope, |id| keys.get(id).cloned()) {
671            Ok(plain) => row[enc.index] = Some(plain_to_column_value(plain)),
672            Err(DecryptValueError::KeyMissing { key_id }) => {
673                missing.get_or_insert(key_id);
674            }
675            Err(DecryptValueError::Failed(error)) => return Err(failed(error.0)),
676        }
677    }
678    let Some(key_id) = missing else {
679        return Ok(None);
680    };
681    for enc in &table.encrypted_columns {
682        row[enc.index] = None;
683    }
684    Ok(Some(SealedRow {
685        key_id,
686        envelopes: Value::Object(envelopes).to_string(),
687    }))
688}
689
690/// §5.11 reveal: decrypt a sealed row's stored `_sync_sealed` envelopes into
691/// a row that holds only its encrypted columns; `None` while the keyring
692/// still lacks one of their keys.
693#[cfg(feature = "e2ee")]
694pub fn reveal_sealed_row(
695    table: &TableSchema,
696    envelopes: &str,
697    encryption: &EncryptionConfig,
698) -> Result<Option<Row>, TransportError> {
699    let corrupt = || TransportError::new("client.decrypt_failed", "sealed envelopes are corrupt");
700    let stored: Map<String, Value> = serde_json::from_str(envelopes).map_err(|_| corrupt())?;
701    let mut row: Row = vec![None; table.columns.len()];
702    for enc in &table.encrypted_columns {
703        if let Some(encoded) = stored.get(&table.columns[enc.index].name) {
704            let bytes = encoded
705                .as_str()
706                .and_then(|encoded| hex_to_bytes(encoded).ok())
707                .ok_or_else(corrupt)?;
708            row[enc.index] = Some(ColumnValue::Bytes(bytes));
709        }
710    }
711    Ok(decrypt_row(table, &mut row, encryption)?
712        .is_none()
713        .then_some(row))
714}
715
716/// Without the `e2ee` feature, a schema with encrypted columns is a
717/// misconfiguration — fail loud rather than ship plaintext.
718#[cfg(not(feature = "e2ee"))]
719fn encrypt_row(
720    table: &TableSchema,
721    _row_id: &str,
722    _row: &mut Row,
723    _encryption: &EncryptionConfig,
724) -> Result<(), String> {
725    Err(format!(
726        "table {:?} has encrypted columns but this build lacks the e2ee feature (§5.11)",
727        table.name
728    ))
729}
730
731#[cfg(not(feature = "e2ee"))]
732pub fn reveal_sealed_row(
733    table: &TableSchema,
734    _envelopes: &str,
735    encryption: &EncryptionConfig,
736) -> Result<Option<Row>, TransportError> {
737    decrypt_row(table, &mut Vec::new(), encryption).map(|_| None)
738}
739
740#[cfg(not(feature = "e2ee"))]
741fn decrypt_row(
742    table: &TableSchema,
743    _row: &mut Row,
744    _encryption: &EncryptionConfig,
745) -> Result<Option<SealedRow>, TransportError> {
746    Err(TransportError::new(
747        "client.decrypt_failed",
748        format!(
749            "table {:?} has encrypted columns but this build lacks the e2ee feature (§5.11)",
750            table.name
751        ),
752    ))
753}
754
755#[cfg(feature = "e2ee")]
756fn column_value_to_plain(value: &ColumnValue) -> Result<ssp2::crypto::PlainValue, String> {
757    use ssp2::crypto::PlainValue;
758    Ok(match value {
759        ColumnValue::String(s) => PlainValue::String(s.clone()),
760        ColumnValue::Integer(i) => PlainValue::Integer(*i),
761        ColumnValue::Float(f) => PlainValue::Float(*f),
762        ColumnValue::Boolean(b) => PlainValue::Boolean(*b),
763        ColumnValue::Json(j) => PlainValue::Json(j.0.clone()),
764        ColumnValue::BlobRef(j) => PlainValue::BlobRef(j.0.clone()),
765        ColumnValue::Bytes(b) => PlainValue::Bytes(b.clone()),
766        ColumnValue::Crdt(_) => return Err("crdt columns cannot be encrypted (§5.11)".to_owned()),
767    })
768}
769
770#[cfg(feature = "e2ee")]
771fn plain_to_column_value(value: ssp2::crypto::PlainValue) -> ColumnValue {
772    use ssp2::crypto::PlainValue;
773    match value {
774        PlainValue::String(s) => ColumnValue::String(s),
775        PlainValue::Integer(i) => ColumnValue::Integer(i),
776        PlainValue::Float(f) => ColumnValue::Float(f),
777        PlainValue::Boolean(b) => ColumnValue::Boolean(b),
778        PlainValue::Json(s) => ColumnValue::Json(RawJson(s)),
779        PlainValue::BlobRef(s) => ColumnValue::BlobRef(RawJson(s)),
780        PlainValue::Bytes(b) => ColumnValue::Bytes(b),
781    }
782}
783
784/// Render a primary-key value as the wire `rowId` string.
785pub fn render_row_id(value: &Option<ColumnValue>) -> Result<String, String> {
786    match value {
787        Some(ColumnValue::String(s)) => Ok(s.clone()),
788        Some(ColumnValue::Integer(i)) => Ok(i.to_string()),
789        Some(ColumnValue::Float(f)) => Ok(f.to_string()),
790        Some(ColumnValue::Boolean(b)) => Ok(b.to_string()),
791        Some(ColumnValue::Json(raw)) => Ok(raw.0.clone()),
792        Some(ColumnValue::BlobRef(_)) => Err("blob_ref column cannot be a rowId".to_owned()),
793        Some(ColumnValue::Bytes(_)) => Err("bytes column cannot be a rowId".to_owned()),
794        Some(ColumnValue::Crdt(_)) => Err("crdt column cannot be a rowId".to_owned()),
795        None => Err("primary key value is missing".to_owned()),
796    }
797}
798
799/// Driver JSON value → wire `rowId` string (for optimistic upserts).
800pub fn render_row_id_json(value: Option<&Value>) -> Result<String, String> {
801    match value {
802        Some(Value::String(s)) => Ok(s.clone()),
803        Some(Value::Number(n)) => Ok(n.to_string()),
804        Some(Value::Bool(b)) => Ok(b.to_string()),
805        _ => Err("sync.invalid_request: primary key value is missing or not renderable".to_owned()),
806    }
807}
808
809/// Scope map as a driver JSON object (`variable → list of values`, §3.2).
810pub fn scope_map_to_json(scopes: &[(String, Vec<String>)]) -> Value {
811    let mut map = Map::new();
812    for (key, values) in scopes {
813        map.insert(
814            key.clone(),
815            Value::Array(values.iter().map(|v| Value::from(v.clone())).collect()),
816        );
817    }
818    Value::Object(map)
819}
820
821/// Driver JSON object → scope map, preserving key order.
822pub fn json_to_scope_map(value: &Value) -> Result<Vec<(String, Vec<String>)>, String> {
823    let object = value
824        .as_object()
825        .ok_or_else(|| "scope map must be an object".to_owned())?;
826    let mut out = Vec::with_capacity(object.len());
827    for (key, values) in object {
828        let list = values
829            .as_array()
830            .ok_or_else(|| format!("scope values for {key:?} must be a list (§0)"))?;
831        let mut strings = Vec::with_capacity(list.len());
832        for v in list {
833            strings.push(
834                v.as_str()
835                    .ok_or_else(|| format!("scope value for {key:?} is not a string"))?
836                    .to_owned(),
837            );
838        }
839        out.push((key.clone(), strings));
840    }
841    Ok(out)
842}
843
844#[cfg(test)]
845mod naming_tests {
846    use serde_json::{json, Map, Value};
847    use ssp2::segment::{Column, ColumnType, ColumnValue, Row};
848
849    use super::{
850        bytes_to_hex, hex_to_bytes, normalize_values_casing, snake_to_camel, EncryptionConfig,
851    };
852    use crate::schema::{EncryptedColumn, TableSchema};
853
854    #[test]
855    fn authored_integer_cells_respect_the_wire_safe_range() {
856        let column = Column {
857            name: "n".into(),
858            ty: ColumnType::Integer,
859            nullable: false,
860        };
861        for value in [
862            9007199254740992_i64,
863            9007199254740993,
864            i64::MAX,
865            -9007199254740992,
866            i64::MIN,
867        ] {
868            assert!(super::json_to_column_value(&column, Some(&json!(value))).is_err());
869        }
870        for value in [-9007199254740991_i64, 0, 9007199254740991] {
871            assert!(super::json_to_column_value(&column, Some(&json!(value))).is_ok());
872        }
873    }
874
875    #[test]
876    fn byte_envelopes_preserve_canonical_hex_for_every_byte() {
877        let bytes: Vec<u8> = (0..=255).collect();
878        let expected: String = bytes.iter().map(|byte| format!("{byte:02x}")).collect();
879        assert_eq!(bytes_to_hex(&bytes), expected);
880        assert_eq!(hex_to_bytes(&expected).expect("decode"), bytes);
881        assert_eq!(bytes_to_hex(&[]), "");
882        assert_eq!(bytes_to_hex(&[0, 15, 16, 255]), "000f10ff");
883        let large = bytes.repeat(8192);
884        assert_eq!(bytes_to_hex(&large), expected.repeat(8192));
885        assert_eq!(
886            hex_to_bytes(&bytes_to_hex(&large)).expect("large decode"),
887            large
888        );
889    }
890
891    #[test]
892    fn byte_decoder_preserves_radix_parser_inputs_and_errors() {
893        for first in 0_u8..=127 {
894            for second in 0_u8..=127 {
895                let pair = [first, second];
896                let input = std::str::from_utf8(&pair).unwrap();
897                let expected = u8::from_str_radix(input, 16)
898                    .map(|byte| vec![byte])
899                    .map_err(|error| format!("bad hex: {error}"));
900                assert_eq!(hex_to_bytes(input), expected, "ASCII pair {pair:?}");
901            }
902        }
903        assert_eq!(hex_to_bytes("+fA0+100"), Ok(vec![15, 160, 1, 0]));
904        for input in [
905            "", "0", "abc", "é", "雪", "😀", "0é0", "é00", "00é", "00😀", "😀00", "\0\0",
906        ] {
907            let expected = if !input.len().is_multiple_of(2) {
908                Err("odd-length hex string".to_owned())
909            } else {
910                input
911                    .as_bytes()
912                    .chunks(2)
913                    .map(|pair| {
914                        let text =
915                            std::str::from_utf8(pair).map_err(|_| "non-ASCII hex".to_owned())?;
916                        u8::from_str_radix(text, 16).map_err(|error| format!("bad hex: {error}"))
917                    })
918                    .collect::<Result<Vec<_>, _>>()
919            };
920            assert_eq!(hex_to_bytes(input), expected, "input {input:?}");
921        }
922    }
923
924    #[test]
925    fn snake_to_camel_pinned_vectors() {
926        for (input, expected) in [
927            ("created_at", "createdAt"),
928            ("col_2", "col2"),
929            ("user_id", "userId"),
930            ("_internal", "_internal"),
931            ("__foo_bar", "__fooBar"),
932            ("row_", "row_"),
933            ("id_url", "idUrl"),
934            ("api_key", "apiKey"),
935            ("title", "title"),
936            ("alreadyCamel", "alreadyCamel"),
937            ("a__b", "aB"),
938            ("_lead_and_trail_", "_leadAndTrail_"),
939            ("count(*)", "count(*)"),
940        ] {
941            assert_eq!(snake_to_camel(input), expected, "input {input:?}");
942        }
943    }
944
945    #[test]
946    fn portable_key_selector_reads_a_non_encrypted_string_column() {
947        let columns = vec![
948            Column {
949                name: "id".to_owned(),
950                ty: ColumnType::String,
951                nullable: false,
952            },
953            Column {
954                name: "encryption_key_id".to_owned(),
955                ty: ColumnType::String,
956                nullable: false,
957            },
958            Column {
959                name: "note".to_owned(),
960                ty: ColumnType::String,
961                nullable: false,
962            },
963        ];
964        let table = TableSchema {
965            name: "patients".to_owned(),
966            columns: columns.clone(),
967            wire_columns: columns,
968            primary_key: "id".to_owned(),
969            pk_index: 0,
970            scope_variables: Vec::new(),
971            indexes: Vec::new(),
972            fts_indexes: Vec::new(),
973            encrypted_columns: vec![EncryptedColumn {
974                index: 2,
975                declared_type: "string".to_owned(),
976            }],
977            server_owned_columns: Vec::new(),
978            generation: None,
979        };
980        let mut config = EncryptionConfig::default();
981        config
982            .key_id_columns
983            .insert("patients".to_owned(), "encryption_key_id".to_owned());
984        let row: Row = vec![
985            Some(ColumnValue::String("patient-1".to_owned())),
986            Some(ColumnValue::String("practice-key-v1".to_owned())),
987            Some(ColumnValue::String("Identity".to_owned())),
988        ];
989        assert_eq!(
990            config.key_id_for(&table, &row).expect("selects key"),
991            "practice-key-v1"
992        );
993    }
994
995    #[test]
996    fn debug_render_redacts_key_material() {
997        let mut config = EncryptionConfig::default();
998        config
999            .keys
1000            .insert("practice-key-v1".to_owned(), vec![0xAB; 32]);
1001        config
1002            .key_id_columns
1003            .insert("patients".to_owned(), "encryption_key_id".to_owned());
1004        let rendered = format!("{config:?}");
1005        assert!(rendered.contains("practice-key-v1"), "{rendered}");
1006        assert!(rendered.contains("<32 bytes>"), "{rendered}");
1007        assert!(rendered.contains("encryption_key_id"), "{rendered}");
1008        // Raw byte values never appear (0xAB renders as 171 under derive).
1009        assert!(!rendered.contains("171"), "{rendered}");
1010        assert!(!rendered.contains("0xAB"), "{rendered}");
1011    }
1012
1013    fn table(names: &[&str]) -> TableSchema {
1014        let columns: Vec<Column> = names
1015            .iter()
1016            .map(|n| Column {
1017                name: (*n).to_owned(),
1018                ty: ColumnType::String,
1019                nullable: true,
1020            })
1021            .collect();
1022        TableSchema {
1023            name: "t".to_owned(),
1024            columns: columns.clone(),
1025            wire_columns: columns,
1026            primary_key: "id".to_owned(),
1027            pk_index: 0,
1028            scope_variables: Vec::new(),
1029            indexes: Vec::new(),
1030            fts_indexes: Vec::new(),
1031            encrypted_columns: Vec::new(),
1032            server_owned_columns: Vec::new(),
1033            generation: None,
1034        }
1035    }
1036
1037    fn map(entries: &[(&str, &str)]) -> Map<String, Value> {
1038        entries
1039            .iter()
1040            .map(|(k, v)| ((*k).to_owned(), json!(v)))
1041            .collect()
1042    }
1043
1044    #[test]
1045    fn camel_keys_normalize_to_sql_names() {
1046        let t = table(&["id", "list_id", "updated_at_ms"]);
1047        let out = normalize_values_casing(
1048            &t,
1049            map(&[("id", "x"), ("listId", "l"), ("updatedAtMs", "9")]),
1050        )
1051        .expect("normalizes");
1052        assert_eq!(out.get("list_id"), Some(&json!("l")));
1053        assert_eq!(out.get("updated_at_ms"), Some(&json!("9")));
1054        assert!(!out.contains_key("listId"));
1055    }
1056
1057    #[test]
1058    fn snake_keys_pass_through() {
1059        let t = table(&["id", "list_id"]);
1060        let out = normalize_values_casing(&t, map(&[("id", "x"), ("list_id", "l")])).expect("ok");
1061        assert_eq!(out.get("list_id"), Some(&json!("l")));
1062    }
1063
1064    #[test]
1065    fn both_casings_for_one_column_is_an_error() {
1066        let t = table(&["id", "list_id"]);
1067        let err = normalize_values_casing(&t, map(&[("list_id", "a"), ("listId", "b")]))
1068            .expect_err("rejects");
1069        assert!(err.contains("both snake_case and camelCase"), "{err}");
1070    }
1071
1072    #[test]
1073    fn an_alias_colliding_with_a_real_column_never_steals_it() {
1074        // `col_2` camel-maps to `col2`, which IS a column: exact wins, no rename.
1075        let t = table(&["id", "col_2", "col2"]);
1076        let out = normalize_values_casing(&t, map(&[("id", "x"), ("col2", "v")])).expect("ok");
1077        assert_eq!(out.get("col2"), Some(&json!("v")));
1078        assert!(!out.contains_key("col_2"));
1079    }
1080
1081    #[test]
1082    fn unknown_and_internal_columns_fail_loud() {
1083        let t = table(&["id", "title"]);
1084        let unknown = normalize_values_casing(&t, map(&[("id", "x"), ("typo", "v")]))
1085            .expect_err("unknown field");
1086        assert!(unknown.contains("unknown column"), "{unknown}");
1087        let internal = normalize_values_casing(&t, map(&[("id", "x"), ("_sync_version", "1")]))
1088            .expect_err("internal field");
1089        assert!(internal.contains("internal sync column"), "{internal}");
1090    }
1091
1092    #[test]
1093    fn a_server_owned_column_is_not_a_mutation_value() {
1094        let mut t = table(&["id", "title", "approved_by"]);
1095        t.server_owned_columns = vec![2];
1096        for key in ["approved_by", "approvedBy"] {
1097            let err = normalize_values_casing(&t, map(&[("id", "x"), (key, "v")]))
1098                .expect_err("server-owned key refused");
1099            assert!(
1100                err.starts_with("sync.invalid_request:")
1101                    && err.contains("a server-owned column is not a mutation value (§6.7)"),
1102                "{err}"
1103            );
1104        }
1105        normalize_values_casing(&t, map(&[("id", "x"), ("title", "v")]))
1106            .expect("authored columns pass");
1107    }
1108}
1109
1110#[cfg(test)]
1111mod sparse_key_tests {
1112    use ssp2::segment::{Column, ColumnType, ColumnValue, Row};
1113
1114    use super::EncryptionConfig;
1115    use crate::schema::{EncryptedColumn, TableSchema};
1116
1117    #[cfg(feature = "e2ee")]
1118    use super::encode_sparse_row_json;
1119    #[cfg(feature = "e2ee")]
1120    use serde_json::{json, Map, Value};
1121
1122    fn keyed_table() -> TableSchema {
1123        let columns = vec![
1124            Column {
1125                name: "id".to_owned(),
1126                ty: ColumnType::String,
1127                nullable: false,
1128            },
1129            Column {
1130                name: "encryption_key_id".to_owned(),
1131                ty: ColumnType::String,
1132                nullable: true,
1133            },
1134            Column {
1135                name: "note".to_owned(),
1136                ty: ColumnType::String,
1137                nullable: true,
1138            },
1139        ];
1140        let wire_columns = vec![
1141            Column {
1142                name: "id".to_owned(),
1143                ty: ColumnType::String,
1144                nullable: false,
1145            },
1146            Column {
1147                name: "encryption_key_id".to_owned(),
1148                ty: ColumnType::String,
1149                nullable: true,
1150            },
1151            Column {
1152                name: "note".to_owned(),
1153                ty: ColumnType::Bytes,
1154                nullable: true,
1155            },
1156        ];
1157        TableSchema {
1158            name: "t".to_owned(),
1159            columns,
1160            wire_columns,
1161            primary_key: "id".to_owned(),
1162            pk_index: 0,
1163            scope_variables: Vec::new(),
1164            indexes: Vec::new(),
1165            fts_indexes: Vec::new(),
1166            encrypted_columns: vec![EncryptedColumn {
1167                index: 2,
1168                declared_type: "string".to_owned(),
1169            }],
1170            server_owned_columns: Vec::new(),
1171            generation: None,
1172        }
1173    }
1174
1175    fn keyed_config() -> EncryptionConfig {
1176        let mut config = EncryptionConfig::default();
1177        config.keys.insert("k1".to_owned(), vec![0x2A; 32]);
1178        config
1179            .key_id_columns
1180            .insert("t".to_owned(), "encryption_key_id".to_owned());
1181        config
1182    }
1183
1184    #[cfg(feature = "e2ee")]
1185    fn values(entries: &[(&str, Value)]) -> Map<String, Value> {
1186        entries
1187            .iter()
1188            .map(|(key, value)| ((*key).to_owned(), value.clone()))
1189            .collect()
1190    }
1191
1192    #[test]
1193    fn key_selection_failures_carry_the_encode_seam_code() {
1194        let table = keyed_table();
1195        let config = keyed_config();
1196        // Absent selector: absent is not NULL and never densifies into one.
1197        let row: Row = vec![
1198            Some(ColumnValue::String("r1".to_owned())),
1199            None,
1200            Some(ColumnValue::String("hi".to_owned())),
1201        ];
1202        let error = config.key_id_for(&table, &row).expect_err("rejects");
1203        assert!(error.starts_with("client.encrypt_failed"), "{error}");
1204        assert!(!error.starts_with("client.decrypt_failed"), "{error}");
1205    }
1206
1207    #[cfg(feature = "e2ee")]
1208    #[test]
1209    fn sparse_patch_without_an_encrypted_slot_needs_no_key() {
1210        let table = keyed_table();
1211        // No keys at all: resolution must be skipped, not failed.
1212        let config = EncryptionConfig::default();
1213        let payload =
1214            encode_sparse_row_json(&table, "r1", &values(&[("id", json!("r1"))]), &config, None)
1215                .expect("encodes without key resolution");
1216        assert!(!payload.is_empty());
1217    }
1218
1219    #[cfg(feature = "e2ee")]
1220    #[test]
1221    fn sparse_patch_falls_back_to_the_stored_key_id() {
1222        let table = keyed_table();
1223        let config = keyed_config();
1224        // The patch presents an encrypted column but not the selector.
1225        let sparse = values(&[("id", json!("r1")), ("note", json!("hi"))]);
1226        let error = encode_sparse_row_json(&table, "r1", &sparse, &config, None)
1227            .expect_err("absent selector with no fallback fails");
1228        assert!(error.contains("client.encrypt_failed"), "{error}");
1229        let fallback: Row = vec![
1230            Some(ColumnValue::String("r1".to_owned())),
1231            Some(ColumnValue::String("k1".to_owned())),
1232            None,
1233        ];
1234        encode_sparse_row_json(&table, "r1", &sparse, &config, Some(&fallback))
1235            .expect("stored key id encrypts the patch");
1236    }
1237
1238    #[cfg(feature = "e2ee")]
1239    #[test]
1240    fn sparse_patch_keeps_a_present_null_selector() {
1241        let table = keyed_table();
1242        let config = keyed_config();
1243        // The patch presents the selector explicitly as NULL alongside an
1244        // encrypted column. Absent is not NULL: the stored row must not
1245        // rescue a present NULL, and a NULL key id is unusable.
1246        let sparse = values(&[
1247            ("id", json!("r1")),
1248            ("encryption_key_id", json!(null)),
1249            ("note", json!("hi")),
1250        ]);
1251        let fallback: Row = vec![
1252            Some(ColumnValue::String("r1".to_owned())),
1253            Some(ColumnValue::String("k1".to_owned())),
1254            None,
1255        ];
1256        let error = encode_sparse_row_json(&table, "r1", &sparse, &config, Some(&fallback))
1257            .expect_err("a present NULL selector must not read the stored fallback");
1258        assert!(error.contains("client.encrypt_failed"), "{error}");
1259    }
1260}