fix(stack): correct the supabase .or() string parser

tobyhede · tobyhede · commit 8cd485d246b6 · 2026-07-09T22:51:20.000+10:00
An `.or()` string is only rebuilt from its parse when it references an
encrypted column — otherwise the caller's string is forwarded verbatim —
so each of these corrupts precisely the mixed encrypted/plaintext case.

Quotes were tracked only at brace depth 0, so a `}` inside a quoted array
element or jsonb string value closed the literal early and the next `"`
re-opened quoting: the following top-level comma never split and its
condition was absorbed into the operand. Quotes are now opaque at every
depth.

A stray `}` or `)` drove the depth counter negative, after which no comma
split again. Neither is a PostgREST reserved character, so `a}b` is a
valid unquoted operand. Depth now floors at zero.

`in`-list elements were split on every comma, ignoring quotes, and the
quotes were left embedded in the fragments. On an encrypted column each
fragment became its own term, so `in.("Doe, John",Smith)` never matched.
Elements are now split on top-level commas and unquoted — the inverse of
what `rebuildOrString` emits.

A parenthesized operand was read as a list for every operator, so
`eq.(foo)` encrypted a JS array rather than the string. Only `in` and the
range operators take a paren-delimited operand.

A string operand spelling `null`/`true`/`false` is now quoted: PostgREST
reads a bare `null` as SQL NULL.

Finally, `contains(col, …)` on a union key spanning an encrypted and a
plaintext column accepted an array or object. A union is only as
permissive as its strictest member; any declared column in it pins the
operand to `string`. A literal column argument was never affected.
diff --git a/.changeset/supabase-or-string-parser.md b/.changeset/supabase-or-string-parser.md
@@ -0,0 +1,19 @@
+---
+'@cipherstash/stack': patch
+---
+
+Fix the Supabase adapter's `.or()` string parser mis-splitting conditions, and pin `contains()` on a mixed union column key to the encrypted operand.
+
+An `.or()` string is only rebuilt from its parse when it references an encrypted column — otherwise the caller's string is forwarded verbatim — so each of these corrupts precisely the mixed encrypted/plaintext case.
+
+**Quotes were tracked only at brace depth 0.** A `}` inside a quoted array element or jsonb string value closed the literal early, and the next `"` re-opened quoting, so the following top-level comma never split: `.or('tags.cs.{"a}b"},email.eq.secret')` parsed as a single condition and silently absorbed `email.eq.secret` into the operand. Quotes are now opaque at every depth.
+
+**A stray `}` or `)` drove the depth counter negative**, after which no comma split again. `}` and `)` are not PostgREST reserved characters, so `a}b` is a valid unquoted operand and `.or('nickname.eq.a}b,id.eq.1')` dropped `id.eq.1`. Depth now floors at zero.
+
+**`in`-list elements were split on every comma, ignoring quotes.** `.or('email.in.("a,b",c)')` parsed as three elements with the quotes still embedded; on an encrypted column each fragment was encrypted as its own term, so the intended element never matched. Elements are now split on top-level commas and unquoted, the inverse of what the rebuild emits.
+
+**A parenthesized operand was read as a list for every operator.** Only `in` and the range operators (`ov`, `sl`, `sr`, `nxr`, `nxl`, `adj`) take a paren-delimited operand; elsewhere `(` is an ordinary character. `email.eq.(foo)` parsed as `['foo']` and encrypted a JS array rather than the string, matching nothing.
+
+**A string operand spelling `null`, `true` or `false` is now quoted.** PostgREST reads a bare `null` as SQL NULL, so `.or([{ column: 'name', op: 'eq', value: 'null' }])` emitted `name.eq.null` and compared against NULL instead of the three-character string.
+
+**`contains(col, …)` where `col` is a union spanning an encrypted and a plaintext column** accepted an array or object operand. The union is now only as permissive as its strictest member: any declared encrypted column in the union pins the operand to `string`. A literal column argument was never affected.
diff --git a/packages/stack/__tests__/supabase-helpers.test.ts b/packages/stack/__tests__/supabase-helpers.test.ts
@@ -256,6 +256,160 @@ describe('parseOrString containment literals', () => {
   })
 })
 
+// A quoted operand is opaque at EVERY depth, and a stray brace or paren in an
+// unquoted value is a literal character, not structure. Tracking quotes only at
+// depth 0 let a `}` inside a quoted array element close the literal early; an
+// unmatched `}` in a plain value drove the depth counter negative, after which no
+// top-level comma ever split again. Both silently absorb the following condition
+// into the preceding operand — and only or-strings that also reference an
+// encrypted column are rebuilt from the parse, so it corrupts precisely the
+// mixed encrypted/plaintext case.
+describe('parseOrString structural characters inside values', () => {
+  it('does not close an array literal on a brace inside a quoted element', () => {
+    expect(parseOrString('tags.cs.{"a}b"},email.eq.secret')).toEqual([
+      { column: 'tags', op: 'cs', negate: false, value: '{"a}b"}' },
+      { column: 'email', op: 'eq', negate: false, value: 'secret' },
+    ])
+  })
+
+  it('does not close a jsonb literal on a brace inside a quoted value', () => {
+    expect(parseOrString('meta.cs.{"a":"v}"},id.eq.1')).toEqual([
+      { column: 'meta', op: 'cs', negate: false, value: '{"a":"v}"}' },
+      { column: 'id', op: 'eq', negate: false, value: '1' },
+    ])
+  })
+
+  // Every structural character, quoted as a jsonb VALUE, with the encrypted
+  // column ahead of the literal and a plaintext condition behind it — the shape
+  // that actually reaches `rebuildOrString`, since the encrypted `email` is what
+  // forces the group to be rebuilt rather than forwarded verbatim.
+  it.each([
+    '}',
+    '{',
+    ')',
+    '(',
+  ])('keeps a quoted %s inside a jsonb literal out of the depth count', (char) => {
+    expect(
+      parseOrString(`email.eq.x,meta.cs.{"a":"${char}"},note.eq.y`),
+    ).toEqual([
+      { column: 'email', op: 'eq', negate: false, value: 'x' },
+      { column: 'meta', op: 'cs', negate: false, value: `{"a":"${char}"}` },
+      { column: 'note', op: 'eq', negate: false, value: 'y' },
+    ])
+  })
+
+  it('keeps an escaped quote inside a jsonb value opaque', () => {
+    // `\"` must not close the element, or the `}` behind it decrements depth.
+    expect(parseOrString('a.eq.1,meta.cs.{"a":"\\"}"},b.eq.2')).toHaveLength(3)
+  })
+
+  it('splits after an unmatched brace in an unquoted value', () => {
+    // `}` is not a PostgREST reserved character, so `a}b` is a valid unquoted
+    // scalar operand.
+    expect(parseOrString('nickname.eq.a}b,id.eq.1')).toEqual([
+      { column: 'nickname', op: 'eq', negate: false, value: 'a}b' },
+      { column: 'id', op: 'eq', negate: false, value: '1' },
+    ])
+  })
+
+  it('splits after an unmatched paren in an unquoted value', () => {
+    expect(parseOrString('a.eq.x),b.eq.y')).toEqual([
+      { column: 'a', op: 'eq', negate: false, value: 'x)' },
+      { column: 'b', op: 'eq', negate: false, value: 'y' },
+    ])
+  })
+})
+
+// An `in`-list element is quoted exactly like any other operand, so the list must
+// be split on top-level commas and each element unquoted. Splitting the raw
+// string on every comma tore `("a,b",c)` into three fragments and left the quotes
+// embedded in them — on an encrypted column each fragment is encrypted as its own
+// term, so the intended element never matches.
+describe('parseOrString in-list elements', () => {
+  it('does not split on a comma inside a quoted element', () => {
+    expect(parseOrString('email.in.("a,b",c)')).toEqual([
+      { column: 'email', op: 'in', negate: false, value: ['a,b', 'c'] },
+    ])
+  })
+
+  it('unescapes a quoted element', () => {
+    expect(parseOrString('a.in.("x\\"y",z)')).toEqual([
+      { column: 'a', op: 'in', negate: false, value: ['x"y', 'z'] },
+    ])
+  })
+
+  it('round-trips a comma-bearing element through rebuild', () => {
+    const s = 'name.in.("Doe, John",Smith)'
+    expect(rebuildOrString(parseOrString(s) as DbPendingOrCondition[])).toBe(s)
+  })
+
+  it('round-trips an encrypted envelope element', () => {
+    const parsed = parseOrString(
+      rebuildOrString([cond('email', 'in', [ENVELOPE, 'x'])]),
+    )
+    expect(parsed).toEqual([
+      { column: 'email', op: 'in', negate: false, value: [ENVELOPE, 'x'] },
+    ])
+  })
+
+  it('splits a negated list on top-level commas only', () => {
+    expect(parseOrString('email.not.in.("a,b",c)')).toEqual([
+      { column: 'email', op: 'in', negate: true, value: ['a,b', 'c'] },
+    ])
+  })
+
+  // Only the operators whose operand PostgREST delimits with parens take a list.
+  // A parenthesized operand anywhere else is a scalar that happens to start with
+  // `(`: parsed as an array, an encrypted `eq` operand is encrypted as a JS array
+  // rather than the intended string, and the filter matches nothing.
+  it('does not read a parenthesized scalar as a list for a scalar operator', () => {
+    expect(parseOrString('email.eq.(foo)')).toEqual([
+      { column: 'email', op: 'eq', negate: false, value: '(foo)' },
+    ])
+  })
+
+  // The range operators take a paren-delimited operand too. Excluding them would
+  // re-emit `period.ov.(1,10)` as a quoted scalar — a wire-format change on a
+  // plaintext column that merely shares an `.or()` with an encrypted one.
+  it.each([
+    'ov',
+    'sl',
+    'sr',
+    'nxr',
+    'nxl',
+    'adj',
+  ])('round-trips a paren-delimited %s operand', (op) => {
+    const s = `period.${op}.(1,10)`
+    expect(parseOrString(s)).toEqual([
+      { column: 'period', op, negate: false, value: ['1', '10'] },
+    ])
+    expect(rebuildOrString(parseOrString(s) as DbPendingOrCondition[])).toBe(s)
+  })
+})
+
+// PostgREST reads a bare `null` / `true` / `false` operand as the SQL value, not
+// as the string spelling it. A string operand that happens to spell one must be
+// quoted, or `name.eq.null` compares against SQL NULL and matches nothing.
+describe('rebuildOrString reserved words', () => {
+  it.each(['null', 'true', 'false'])('quotes the string %s', (word) => {
+    expect(rebuildOrString([cond('name', 'eq', word)])).toBe(
+      `name.eq."${word}"`,
+    )
+  })
+
+  it('leaves the SQL values unquoted', () => {
+    expect(rebuildOrString([cond('a', 'is', null)])).toBe('a.is.null')
+    expect(rebuildOrString([cond('a', 'is', true)])).toBe('a.is.true')
+    expect(rebuildOrString([cond('a', 'is', false)])).toBe('a.is.false')
+  })
+
+  it('quotes a reserved word inside an in-list', () => {
+    expect(rebuildOrString([cond('a', 'in', ['null', 'x'])])).toBe(
+      'a.in.("null",x)',
+    )
+  })
+})
+
 describe('parseOrString negation', () => {
   it('lifts a not. prefix off the operator', () => {
     expect(parseOrString('nickname.not.eq.ada')).toEqual([
diff --git a/packages/stack/__tests__/supabase-v3.test-d.ts b/packages/stack/__tests__/supabase-v3.test-d.ts
@@ -33,6 +33,11 @@ declare const mixedBuilder: EncryptedQueryBuilderV3<
   UserRow & { tags: string[]; meta: Record<string, unknown> }
 >
 
+/** A column key that is a UNION spanning an encrypted and a plaintext column. */
+declare const mixedKey: 'email' | 'tags'
+/** A column key that is a union of plaintext columns only. */
+declare const plaintextKey: 'tags' | 'meta'
+
 describe('encryptedSupabaseV3 typed surface (with schemas)', () => {
   it('rows carry each column its domain plaintext type', async () => {
     const supabase = await encryptedSupabaseV3(supabaseClient, {
@@ -144,6 +149,24 @@ describe('encryptedSupabaseV3 typed surface (with schemas)', () => {
     mixedBuilder.contains('bio', { a: 1 })
   })
 
+  // A union column key is only as permissive as its STRICTEST member. If any
+  // member is a declared encrypted column the operand must be the string term:
+  // that member's runtime path hands the operand to `encrypt()`, which has no
+  // plaintext-type guard, so an array reaches protect-ffi as the plaintext for a
+  // `cast_as: text` column.
+  it('pins a mixed union key to the encrypted string operand', () => {
+    mixedBuilder.contains(mixedKey, 'ada')
+    // @ts-expect-error — the union includes email (public.text_search)
+    mixedBuilder.contains(mixedKey, ['vip'])
+    // @ts-expect-error — the union includes email (public.text_search)
+    mixedBuilder.contains(mixedKey, { plan: 'pro' })
+  })
+
+  it('leaves a union of plaintext keys on the native operand', () => {
+    mixedBuilder.contains(plaintextKey, ['vip'])
+    mixedBuilder.contains(plaintextKey, { plan: 'pro' })
+  })
+
   it('does not expose like/ilike on the v3 builder, at any chain depth', async () => {
     const supabase = await encryptedSupabaseV3(supabaseClient, {
       schemas: { users },
diff --git a/packages/stack/src/supabase/helpers.ts b/packages/stack/src/supabase/helpers.ts
@@ -220,7 +220,7 @@ export function mapFilterOpToQueryType(op: FilterOp): QueryTypeName {
 export function parseOrString(orString: string): PendingOrCondition[] {
   const conditions: PendingOrCondition[] = []
   // Split on commas that are not inside parentheses (nested or/and)
-  const parts = splitOrString(orString)
+  const parts = splitTopLevel(orString)
 
   for (const part of parts) {
     const trimmed = part.trim()
@@ -252,7 +252,7 @@ export function parseOrString(orString: string): PendingOrCondition[] {
     const value = rest.slice(secondDot + 1)
 
     // Handle special value formats
-    const parsedValue = parseOrValue(value)
+    const parsedValue = parseOrValue(value, op)
 
     conditions.push({ column, op, negate, value: parsedValue })
   }
@@ -310,7 +310,22 @@ export function rebuildOrString(
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-function splitOrString(input: string): string[] {
+/**
+ * Split on the commas that separate top-level tokens, leaving those inside a
+ * quoted operand or a `(…)` / `{…}` literal alone.
+ *
+ * Quotes are tracked at EVERY depth. A quoted string is opaque wherever it
+ * appears, and an array literal quotes any element carrying a reserved character
+ * (see {@link arrayLiteralElement}) — so `{"a}b"}` closes at the LAST brace, not
+ * the one inside the element. Tracking quotes only at depth 0 ended the literal
+ * early and swallowed the following condition into this operand.
+ *
+ * `depth` never goes below zero. `}` and `)` are not PostgREST reserved
+ * characters, so `a}b` is a valid unquoted scalar; letting a stray one decrement
+ * past zero meant no later comma ever split, silently absorbing every remaining
+ * condition.
+ */
+function splitTopLevel(input: string): string[] {
   const parts: string[] = []
   let current = ''
   let depth = 0
@@ -328,7 +343,7 @@ function splitOrString(input: string): string[] {
     } else if (char === '\\' && inQuotes) {
       escaped = true
       current += char
-    } else if (char === '"' && depth === 0) {
+    } else if (char === '"') {
       inQuotes = !inQuotes
       current += char
     } else if ((char === '(' || char === '{') && !inQuotes) {
@@ -340,7 +355,7 @@ function splitOrString(input: string): string[] {
       depth++
       current += char
     } else if ((char === ')' || char === '}') && !inQuotes) {
-      depth--
+      depth = Math.max(0, depth - 1)
       current += char
     } else if (char === ',' && depth === 0 && !inQuotes) {
       parts.push(current)
@@ -350,27 +365,60 @@ function splitOrString(input: string): string[] {
     }
   }
 
-  if (current) {
-    parts.push(current)
-  }
+  parts.push(current)
 
   return parts
 }
 
-function parseOrValue(value: string): unknown {
+/**
+ * One element of an `in`-list operand, undoing {@link formatOrValue}'s quoting.
+ * Unquoted elements are trimmed, as PostgREST ignores whitespace around them;
+ * inside quotes it is significant.
+ */
+function parseInListElement(element: string): string {
+  const trimmed = element.trim()
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    return unescapeOrValue(trimmed.slice(1, -1))
+  }
+  return trimmed
+}
+
+/**
+ * PostgREST operators whose operand is delimited by parentheses: the `in` list
+ * and the range operators. Everywhere else `(` is an ordinary character, and a
+ * parenthesized operand is a scalar that happens to start with one.
+ *
+ * The range operators earn their place by round-trip fidelity rather than by
+ * encryption: none is supported on an encrypted column, but an or-string is
+ * rebuilt whole as soon as ANY of its conditions names one, so a plaintext
+ * `period.ov.(1,10)` sharing the group must re-emit byte-for-byte.
+ */
+const PAREN_OPERAND_OPS = new Set(['in', 'ov', 'sl', 'sr', 'nxr', 'nxl', 'adj'])
+
+/**
+ * @param op the operator the value belongs to, already stripped of any `not.`
+ * prefix. Parsing a parenthesized scalar as an array meant an encrypted `eq`
+ * operand was encrypted as a JS array rather than the intended string, and the
+ * filter matched nothing.
+ */
+function parseOrValue(value: string, op?: string): unknown {
   // Handle double-quoted values (PostgREST quoting for reserved characters).
   // Must undo `escapeOrValue`, or a parse → rebuild round-trip doubles every
   // backslash. The two functions are only correct as a pair.
   if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
     return unescapeOrValue(value.slice(1, -1))
   }
 
-  // Handle parenthesized lists: (val1,val2,val3)
-  if (value.startsWith('(') && value.endsWith(')')) {
-    return value
-      .slice(1, -1)
-      .split(',')
-      .map((v) => v.trim())
+  // Handle parenthesized lists: (val1,val2,val3). Elements are quoted exactly as
+  // any other operand, so the split must respect those quotes: `("a,b",c)` is
+  // two elements, not three.
+  if (
+    op !== undefined &&
+    PAREN_OPERAND_OPS.has(op) &&
+    value.startsWith('(') &&
+    value.endsWith(')')
+  ) {
+    return splitTopLevel(value.slice(1, -1)).map(parseInListElement)
   }
 
   // Handle booleans
@@ -395,6 +443,14 @@ function parseOrValue(value: string): unknown {
  */
 const POSTGREST_RESERVED = /["\\,().]/
 
+/**
+ * Operands PostgREST reads as SQL values rather than as the string spelling
+ * them. A STRING operand that happens to spell one must be quoted, or
+ * `name.eq.null` compares against SQL NULL — a filter that matches nothing —
+ * instead of against the three-character string.
+ */
+const POSTGREST_RESERVED_WORDS = new Set(['null', 'true', 'false'])
+
 /** Escape `\` first, then `"` — the reverse order would double-escape. */
 function escapeOrValue(str: string): string {
   return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
@@ -460,7 +516,7 @@ function formatOrValue(value: unknown, op?: string): string {
   // Wrap in double quotes if the value contains reserved characters.
   // This is required for encrypted values (JSON with commas, braces, etc.)
   // and is safe for all string values per PostgREST spec.
-  if (POSTGREST_RESERVED.test(str)) {
+  if (POSTGREST_RESERVED.test(str) || POSTGREST_RESERVED_WORDS.has(str)) {
     return `"${escapeOrValue(str)}"`
   }
 
diff --git a/packages/stack/src/supabase/types.ts b/packages/stack/src/supabase/types.ts
