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