fix(stack): close v3 drizzle fail-open paths, fix false-negative tests

An audit of the EQL v3 Drizzle adapter found the index/query-type wiring
correct, but several tests unable to detect the bug they guard. Three stayed
green under the exact regression they existed to catch, and two source paths
failed open.

Source:

- `contains` now rejects a needle shorter than the tokenizer's `token_length`.
  A short needle builds an EMPTY bloom filter and `stored_bf @> '{}'` holds for
  every row. Measured live: needles "ad", "a" and "x" each returned 3/3 seeded
  rows -- "x" occurs in none of them. The floor lives in `schema/match-defaults`
  so v2 and v3 share it; they build byte-identical blooms.
- `v3FromDriver` throws the new `EqlV3CodecError` rather than surfacing a raw
  SyntaxError on malformed JSON or passing a wrong-shape payload through:
  `v3FromDriver('5')` returned `5` typed as `Encrypted`. The shape guard accepts
  SteVec documents, whose ciphertext is at `sv[0].c` with no top-level `c`.
- Removed the unreachable `sql`false`` fallback in `inArray`/`notInArray`; the
  empty-list guard throws first.

Tests (each verified RED against the bug it guards, then reverted):

- `and` was indistinguishable from `or`: both predicates were true for ROW_B
  alone, so swapping the operator still passed. Now paired over disjoint rows
  and asserted from both directions.
- bigint filters ran against a one-row table, where `gt` returning every row
  passed. Seeded a negative row they must exclude.
- `between` was only ever called with identical bounds against a constant
  encrypt stub, so a min/max transposition in `range` was invisible. Added an
  echoing stub that pins operand order.
- `contains` had no needle that must NOT match, and none longer than
  `token_length`. The unit test searched `TEXT_S[0]` -- the empty string --
  i.e. it asserted the fail-open. Now drives four needles through a substring
  oracle, including a negative one.
- Seeded a third matrix row. With two, every predicate could only return [A],
  [B], [A,B] or [] -- ordering ties were untestable and `eq` over-matching
  undetectable. Row `i` takes `samples[min(i, len-1)]`, the scheme
  `v3-matrix/matrix-live-pg` already uses.

Lock context:

The suite supplied the same context on seed and query in every test, so a
regression dropping it from the index term would drop it identically on both
sides and stay green. Added the negatives obtainable with one JWT: an
identity-bound row must not match an `eq` issued with no lock context, and must
not decrypt without it. A cross-identity proof needs a second JWT with a
different `sub` and remains a follow-up.

`lock-context.test.ts` wrapped `decryptModel` in try/catch, but it reports
denial as a `Result` and never throws -- the test ran zero assertions and would
also have passed had decryption wrongly succeeded.

Smaller pins: sql-dialect asserts operands BIND rather than interpolate;
schema-extraction uses toStrictEqual; the barrel is pinned exhaustively; codec
fixtures are realistic envelopes; the column's customType mappers are exercised.

Not included, per plan: the SQL `bloom_filter` empty-array change (contradicts
a documented semantic; needs sign-off) and the Supabase needle guard (lives on
another branch).

Author: tobyhede

.changeset/eql-v3-drizzle-fail-open-guards.md

@@ -0,0 +1,25 @@
+---
+'@cipherstash/stack': minor
+---
+
+Close two fail-open paths in the EQL v3 Drizzle adapter.
+
+`ops.contains()` now throws `EncryptionOperatorError` when the search term is
+shorter than the match index tokenizer's `token_length` (3 by default). Such a
+term produces no ngrams, so its bloom filter is empty — and `stored_bf @> '{}'`
+is true for every row. Previously a user searching `"ad"` silently received the
+entire table; measured live, the needles `"ad"`, `"a"` and `"x"` each returned
+every seeded row, including one in which `"x"` did not appear. The length floor
+is shared with the v2 adapter via `matchNeedleError` in `schema/match-defaults`,
+since both build byte-identical bloom filters.
+
+`v3FromDriver()` now throws the new `EqlV3CodecError` on a payload that is not
+an EQL envelope, instead of surfacing a raw `SyntaxError` for malformed JSON and
+passing a bare scalar through unchecked — `v3FromDriver('5')` previously returned
+`5` typed as `Encrypted`, which then reached `decrypt` as garbage. The guard
+accepts both scalar envelopes (ciphertext at `c`) and SteVec documents
+(ciphertext at `sv[0].c`). `EqlV3CodecError` is exported from
+`@cipherstash/stack/eql/v3/drizzle` so callers can catch it.
+
+Also removes an unreachable branch in `inArray`/`notInArray`, whose empty-list
+guard already throws before it.

packages/stack/__tests__/drizzle-v3/codec.test.ts

@@ -1,23 +1,62 @@
 import { describe, expect, it } from 'vitest'
-import { v3FromDriver, v3ToDriver } from '@/eql/v3/drizzle/codec'
+import {
+  EqlV3CodecError,
+  v3FromDriver,
+  v3ToDriver,
+} from '@/eql/v3/drizzle/codec'
+
+// A realistic `public.text_eq` envelope: schema version, table/column
+// identifier, mp_base85 ciphertext, HMAC term. The trivial `{v:1,c:'ct'}`
+// fixture this replaced could not distinguish an envelope from a bare object.
+const ENVELOPE = {
+  v: 3,
+  i: { t: 'users', c: 'email' },
+  c: 'mBbKmbNmNhX@Vv0N%<Ke7fH(=Zc*d4rDy0h3~yPZLq!kGm8x7$2Fw<TnR>1jQvA',
+  hm: '3a1f9c0e5b7d2a48e6c1f0b93d7a2e58c4b6f19d0e3a7c25b8f14d69a0c3e7b2',
+} as const
+
+// SteVec documents carry the root ciphertext at `sv[0].c` and have no top-level
+// `c` — the envelope guard must accept them.
+const STE_VEC_ENVELOPE = {
+  v: 3,
+  k: 'sv',
+  i: { t: 'users', c: 'profile' },
+  sv: [{ c: 'mBbKciphertext', s: 'selector', b: 'term' }],
+} as const
 
 describe('v3 codec', () => {
-  it('serialises an object to a jsonb string', () => {
-    expect(v3ToDriver({ v: 1, c: 'ct' })).toBe('{"v":1,"c":"ct"}')
+  it('serialises an envelope to a jsonb string', () => {
+    expect(v3ToDriver(ENVELOPE as never)).toBe(JSON.stringify(ENVELOPE))
   })
 
   it('maps null/undefined to SQL NULL (JS null), never the JSON null literal', () => {
     expect(v3ToDriver(null)).toBeNull()
     expect(v3ToDriver(undefined)).toBeNull()
   })
 
-  it('parses a jsonb string back to an object', () => {
-    expect(v3FromDriver('{"v":1,"c":"ct"}')).toEqual({ v: 1, c: 'ct' })
+  it('round-trips a realistic envelope through both directions', () => {
+    const serialised = v3ToDriver(ENVELOPE as never)
+    expect(v3FromDriver(serialised)).toEqual(ENVELOPE)
+  })
+
+  it('round-trips unicode and a long ciphertext', () => {
+    const envelope = {
+      ...ENVELOPE,
+      i: { t: 'users', c: 'café_☕' },
+      c: 'z'.repeat(8192),
+    }
+    expect(v3FromDriver(v3ToDriver(envelope as never))).toEqual(envelope)
+  })
+
+  it('passes an already-parsed envelope through unchanged', () => {
+    expect(v3FromDriver(ENVELOPE as never)).toBe(ENVELOPE)
   })
 
-  it('passes an already-parsed object through unchanged', () => {
-    const obj = { v: 1 }
-    expect(v3FromDriver(obj)).toBe(obj)
+  it('accepts a SteVec document, whose ciphertext lives at sv[0].c', () => {
+    expect(v3FromDriver(STE_VEC_ENVELOPE as never)).toBe(STE_VEC_ENVELOPE)
+    expect(v3FromDriver(JSON.stringify(STE_VEC_ENVELOPE))).toEqual(
+      STE_VEC_ENVELOPE,
+    )
   })
 
   it('normalises null/undefined to SQL NULL (JS null) on read', () => {
@@ -26,6 +65,44 @@ describe('v3 codec', () => {
   })
 
   it('does not throw on a stray bigint in the envelope (defensive)', () => {
-    expect(v3ToDriver({ v: 1n } as never)).toBe('{"v":"1"}')
+    expect(v3ToDriver({ ...ENVELOPE, v: 3n } as never)).toContain('"v":"3"')
+  })
+
+  // Before these, a malformed string surfaced a raw SyntaxError and a
+  // wrong-shape payload was returned as-is — `v3FromDriver('5')` yielded `5`
+  // typed as an envelope, which then reached `decrypt` as garbage.
+  describe('malformed and non-envelope payloads', () => {
+    it.each([
+      '{bad',
+      '',
+      '{"v":3,',
+    ])('throws EqlV3CodecError on unparseable jsonb %j', (raw) => {
+      expect(() => v3FromDriver(raw)).toThrow(EqlV3CodecError)
+      expect(() => v3FromDriver(raw)).toThrow(/Failed to parse/)
+    })
+
+    it.each([
+      '5',
+      '"a string"',
+      'true',
+      '[]',
+      '[{"v":3,"c":"ct"}]',
+    ])('throws on valid JSON %j that is not an envelope', (raw) => {
+      expect(() => v3FromDriver(raw)).toThrow(EqlV3CodecError)
+    })
+
+    it('throws on an object missing the schema version', () => {
+      expect(() => v3FromDriver({ c: 'ct' })).toThrow(/missing "v"/)
+    })
+
+    it('throws on an object carrying no ciphertext', () => {
+      expect(() => v3FromDriver({ v: 3, i: { t: 'u', c: 'e' } })).toThrow(
+        /missing a ciphertext/,
+      )
+    })
+
+    it('throws on an array', () => {
+      expect(() => v3FromDriver([ENVELOPE] as never)).toThrow(/got an array/)
+    })
   })
 })

packages/stack/__tests__/drizzle-v3/column.test.ts

@@ -133,4 +133,45 @@ describe('makeEqlV3Column', () => {
     expect(pgColumn?.getSQLType()).toBe(eqlType)
     expect(getEqlV3Column(columnName, pgColumn)?.getEqlType()).toBe(eqlType)
   })
+
+  // The `toDriver`/`fromDriver` closures wired into `customType` (column.ts) are
+  // otherwise only tested via the standalone codec functions, so the wiring
+  // itself — including the SQL-NULL safety net — was never exercised.
+  describe('codec wiring on the built column', () => {
+    type Mapper = {
+      mapToDriverValue(value: unknown): unknown
+      mapFromDriverValue(value: unknown): unknown
+    }
+    const mapperFor = (name: string): Mapper => {
+      const table = pgTable('users', {
+        [name]: makeEqlV3Column(v3Types.TextEq(name)),
+      } as never)
+      return (table as unknown as Record<string, Mapper>)[name]
+    }
+
+    const ENVELOPE = {
+      v: 3,
+      i: { t: 'users', c: 'nickname' },
+      c: 'mBbKciphertext',
+      hm: 'hmac',
+    }
+
+    it('serialises an envelope on write and parses it back on read', () => {
+      const column = mapperFor('nickname')
+      const driverValue = column.mapToDriverValue(ENVELOPE)
+
+      expect(driverValue).toBe(JSON.stringify(ENVELOPE))
+      expect(column.mapFromDriverValue(driverValue)).toEqual(ENVELOPE)
+    })
+
+    it('maps a null envelope to SQL NULL on write', () => {
+      expect(mapperFor('nickname').mapToDriverValue(null)).toBeNull()
+    })
+
+    it('rejects a non-envelope driver value rather than passing it through', () => {
+      expect(() => mapperFor('nickname').mapFromDriverValue('5')).toThrow(
+        /EQL encrypted envelope/,
+      )
+    })
+  })
 })

packages/stack/__tests__/drizzle-v3/exports.test.ts

@@ -1,12 +1,41 @@
 import { describe, expect, it } from 'vitest'
 import * as barrel from '@/eql/v3/drizzle'
 
+// Exhaustive, so ADDING an export fails here too. The previous version asserted
+// only four names, leaving the codec/column re-exports unpinned and letting a
+// new export slip into the public surface unnoticed.
+const PUBLIC_SURFACE = [
+  'EncryptionOperatorError',
+  'EqlV3CodecError',
+  'createEncryptionOperatorsV3',
+  'extractEncryptionSchemaV3',
+  'getEqlV3Column',
+  'isEqlV3Column',
+  'makeEqlV3Column',
+  'types',
+  'v3FromDriver',
+  'v3ToDriver',
+] as const
+
 describe('v3 drizzle barrel', () => {
+  it('exports exactly the public surface', () => {
+    expect(Object.keys(barrel).sort()).toEqual([...PUBLIC_SURFACE])
+  })
+
   it('exports the public surface', () => {
     expect(typeof barrel.createEncryptionOperatorsV3).toBe('function')
     expect(typeof barrel.extractEncryptionSchemaV3).toBe('function')
     expect(typeof barrel.EncryptionOperatorError).toBe('function')
+    expect(typeof barrel.EqlV3CodecError).toBe('function')
     expect(typeof barrel.types.TextSearch).toBe('function')
     expect(barrel.types.IntegerOrd('age')).toBeDefined()
   })
+
+  it('re-exports the codec and column helpers as callables', () => {
+    expect(typeof barrel.v3ToDriver).toBe('function')
+    expect(typeof barrel.v3FromDriver).toBe('function')
+    expect(typeof barrel.getEqlV3Column).toBe('function')
+    expect(typeof barrel.isEqlV3Column).toBe('function')
+    expect(typeof barrel.makeEqlV3Column).toBe('function')
+  })
 })