fix(stack): reject empty SteVec, pin ops.and positive path

Address review findings on the v3 Drizzle adapter.

assertEnvelope accepted `sv: []`, which satisfies `sv !== undefined` but has
no `sv[0].c` — the guard's own premise. An empty, non-array, or null `sv`
carries a ciphertext key but no ciphertext, and reached decrypt as garbage.
Require a non-empty array. No encrypt path produces this, so it is hardening
against a corrupt or hostile row rather than a live fail-open.

needleFor selected samples with `sample.length >= 3`, counting UTF-16 code
units where the production guard counts codepoints. An astral sample ('👍👍':
4 units, 2 codepoints) would be picked here and then rejected by the guard,
blaming the wrong line. Latent only because every match-domain sample is
currently ASCII. Extract it to v3-matrix/needle-for.ts and select with
matchNeedleError itself, so the two cannot diverge; it now also honours a
domain's own token_length.

Pairing `and` over disjoint rows proved it is not `or`, but left every live
`and` assertion expecting []. A constant-false `and` would satisfy that, and
the `or` tests exercise a different operator. Restore the intersecting pair
alongside it, so one live test proves `and` returns its row.

The ['email'] lock-context test pinned /^Failed to retrieve key/. Naming a
claim does not assert the token carries it: resolveLockContext is a
passthrough and ZeroKMS resolves the value server-side, so a token with no
`email` claim may be refused by authorization before key derivation is
attempted. Accept either denial class, reject infrastructure faults
explicitly. Kept loose because CI never runs this path (USER_JWT unset, #530).

Collapse exports.test.ts from three tests to two: the two typeof sweeps were
one sweep artificially split. The remaining sweep iterates Object.entries, so
it cannot silently skip a name the key list forgot.

The v2 like/ilike path has the same bloom-containment fail-open and remains
unfixed here, as the changeset already notes.

Author: tobyhede

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

@@ -24,8 +24,10 @@ 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.
+(ciphertext at `sv[0].c`). A SteVec's `sv` must be a non-empty array: `sv[0]` is
+the decryption root, so `sv: []` carries a ciphertext key but no ciphertext, and
+is now rejected rather than passed to `decrypt`. `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

@@ -59,6 +59,21 @@ describe('v3 codec', () => {
     )
   })
 
+  // `sv: []` has no `sv[0]`, so the guard's premise — a ciphertext at the
+  // decryption root — does not hold. Presence of the key is not enough.
+  it.each([
+    ['an empty SteVec', { v: 3, k: 'sv', sv: [] }],
+    ['a non-array SteVec', { v: 3, k: 'sv', sv: {} }],
+    ['a null SteVec with no c', { v: 3, k: 'sv', sv: null }],
+  ])('rejects %s', (_label, envelope) => {
+    expect(() => v3FromDriver(envelope as never)).toThrow(EqlV3CodecError)
+    expect(() => v3FromDriver(envelope as never)).toThrow(/ciphertext/)
+  })
+
+  it('still accepts a scalar envelope, which has c and no sv', () => {
+    expect(v3FromDriver(ENVELOPE as never)).toBe(ENVELOPE)
+  })
+
   it('normalises null/undefined to SQL NULL (JS null) on read', () => {
     expect(v3FromDriver(null)).toBeNull()
     expect(v3FromDriver(undefined)).toBeNull()
@@ -85,20 +100,21 @@ describe('v3 codec', () => {
     // preserve. Flattening it to a message string discards the SyntaxError and
     // its stack, so a caller debugging a corrupt column loses where parsing
     // actually broke.
-    it.each(['{bad', '', '{"v":3,'])(
-      'preserves the underlying SyntaxError as `cause` for %j',
-      (raw) => {
-        let thrown: unknown
-        try {
-          v3FromDriver(raw)
-        } catch (error) {
-          thrown = error
-        }
-
-        expect(thrown).toBeInstanceOf(EqlV3CodecError)
-        expect((thrown as EqlV3CodecError).cause).toBeInstanceOf(SyntaxError)
-      },
-    )
+    it.each([
+      '{bad',
+      '',
+      '{"v":3,',
+    ])('preserves the underlying SyntaxError as `cause` for %j', (raw) => {
+      let thrown: unknown
+      try {
+        v3FromDriver(raw)
+      } catch (error) {
+        thrown = error
+      }
+
+      expect(thrown).toBeInstanceOf(EqlV3CodecError)
+      expect((thrown as EqlV3CodecError).cause).toBeInstanceOf(SyntaxError)
+    })
 
     it.each([
       '5',

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

@@ -22,20 +22,19 @@ describe('v3 drizzle barrel', () => {
     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')
+  // The key check above sees names, not values: a re-export that resolves to
+  // `undefined` still lists its key. Sweep every export the barrel claims.
+  it('exports every name as a callable, and types as a namespace', () => {
+    const callables = Object.entries(barrel).filter(
+      ([name]) => name !== 'types',
+    )
+    expect(callables).toHaveLength(PUBLIC_SURFACE.length - 1)
+
+    for (const [name, value] of callables) {
+      expect(typeof value, name).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')
-  })
 })

packages/stack/__tests__/drizzle-v3/operators-live-pg.test.ts

@@ -666,6 +666,22 @@ describeLivePg('v3 drizzle operators (live pg matrix)', () => {
     expect(rows).toEqual([])
   }, 30000)
 
+  // The disjoint pair above proves `and` is not `or`, but every `and` assertion
+  // over it expects []. A constant-false `and` would satisfy that too, and the
+  // `or` tests exercise a different operator. This pins the positive path:
+  // an intersecting pair that must actually return its row.
+  //   text_eq = 'ada@example.com' -> ROW_B only
+  //   integer_ord < 0             -> ROW_B (-42) only
+  it('and returns the rows satisfying both encrypted predicates', async () => {
+    const rows = await selectRowKeys(
+      await ops.and(
+        ops.eq(matrixColumn('public.text_eq'), 'ada@example.com'),
+        ops.lt(matrixColumn('public.integer_ord'), 0),
+      ),
+    )
+    expect(rows).toEqual([ROW_B])
+  }, 30000)
+
   it('or requires either encrypted predicate, unlike and', async () => {
     const rows = await selectRowKeys(await ops.or(...disjointPredicates()))
     expect(rows).toEqual([ROW_A, ROW_B, ROW_C])

packages/stack/__tests__/drizzle-v3/operators-lock-context-live-pg.test.ts

@@ -116,6 +116,27 @@ async function decryptOutcome(
  */
 const KEY_DENIAL = /^Failed to retrieve key/
 
+/**
+ * Denial under a claim the token may not carry at all. Naming a claim does not
+ * assert it exists: `resolveLockContext` is a passthrough, and ZeroKMS resolves
+ * the claim's value from the authenticating token. So decrypting under
+ * `['email']` a row sealed under `['sub']` either fails key derivation, or — if
+ * the token has no `email` claim — is refused by the authorization layer before
+ * key derivation is ever attempted. Both are denials; which one surfaces is a
+ * ZeroKMS server-side detail we do not pin.
+ *
+ * What must NOT pass is an infrastructure fault masquerading as a denial, so
+ * that is excluded separately. Kept loose rather than pinned to `KEY_DENIAL`
+ * because no CI run exercises this path — `USER_JWT` is unset in CI (#530) —
+ * and a wrong message-shape guess would only surface once that secret lands.
+ */
+const IDENTITY_DENIAL =
+  /failed to retrieve key|unauthoriz|unauthoris|forbidden|denied|not authorized|not authorised/i
+
+/** A transport/outage failure, which must never be mistaken for a denial. */
+const INFRA_FAULT =
+  /ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up|timed? ?out|network error/i
+
 /** Run-scoped SELECT of row keys under an already-encrypted SQL condition. */
 async function selectRowKeys(condition: SQL): Promise<string[]> {
   const rows = (await db
@@ -271,6 +292,7 @@ describeLivePg('v3 drizzle operators with lock context (live pg)', () => {
     )
 
     expect(denied).toBe(true)
-    expect(message).toMatch(KEY_DENIAL)
+    expect(message).toMatch(IDENTITY_DENIAL)
+    expect(message).not.toMatch(INFRA_FAULT)
   }, 30000)
 })

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

@@ -23,6 +23,7 @@ import {
   typedEntries,
   V3_MATRIX,
 } from '../v3-matrix/catalog'
+import { needleFor } from '../v3-matrix/needle-for'
 
 const TERM = { c: 'ct', v: 1 }
 const TERM_JSON = JSON.stringify(TERM)
@@ -99,21 +100,6 @@ const matrixColumn = (eqlType: string) =>
 const sampleFor = (spec: (typeof V3_MATRIX)[keyof typeof V3_MATRIX]) =>
   spec.samples[0]
 
-// `contains` needles must reach the match tokenizer's `token_length` (3), so
-// they cannot come from `sampleFor` — `TEXT_S[0]` is the empty string, which
-// tokenizes to nothing and is rejected as unanswerable.
-const needleFor = (
-  spec: (typeof V3_MATRIX)[keyof typeof V3_MATRIX],
-): string => {
-  const needle = spec.samples.find(
-    (sample) => typeof sample === 'string' && sample.length >= 3,
-  )
-  if (typeof needle !== 'string') {
-    throw new Error('no searchable sample for a match domain')
-  }
-  return needle
-}
-
 const equalityDomains = matrixEntries.filter(
   ([, spec]) => spec.indexes.unique || spec.indexes.ore,
 )

packages/stack/__tests__/v3-matrix/needle-for.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { matchNeedleError } from '@/schema/match-defaults'
+import { V3_MATRIX } from './catalog'
+import { needleFor } from './needle-for'
+
+const MATCH_BLOCK = { tokenizer: { kind: 'ngram', token_length: 3 } } as const
+
+const specWith = (samples: readonly unknown[]) =>
+  ({ samples, indexes: { match: MATCH_BLOCK } }) as never
+
+describe('needleFor', () => {
+  // The guard counts codepoints; a UTF-16 `.length` check would wave '👍👍'
+  // through (4 code units, 2 codepoints) and the `contains` test would then
+  // fail inside the production guard, pointing at the wrong line.
+  it('skips an astral sample that the production guard would reject', () => {
+    expect(needleFor(specWith(['👍👍', 'ada@example.com']))).toBe(
+      'ada@example.com',
+    )
+  })
+
+  it('skips the empty sample', () => {
+    expect(needleFor(specWith(['', 'Ada Lovelace']))).toBe('Ada Lovelace')
+  })
+
+  it('skips non-string samples', () => {
+    expect(needleFor(specWith([42, null, 'Ada']))).toBe('Ada')
+  })
+
+  it('throws when no sample can be searched', () => {
+    expect(() => needleFor(specWith(['', 'ab', '👍👍']))).toThrow(
+      /no searchable sample/,
+    )
+  })
+
+  it('honours a larger token_length', () => {
+    const spec = {
+      samples: ['ada', 'adam'],
+      indexes: { match: { tokenizer: { kind: 'ngram', token_length: 4 } } },
+    } as never
+    expect(needleFor(spec)).toBe('adam')
+  })
+
+  // The contract that matters: whatever it picks, the guard must accept.
+  it('never returns a needle the guard rejects, across every match domain', () => {
+    const matchDomains = Object.values(V3_MATRIX).filter(
+      (spec) => spec.indexes.match,
+    )
+    expect(matchDomains.length).toBeGreaterThan(0)
+
+    for (const spec of matchDomains) {
+      const needle = needleFor(spec)
+      expect(matchNeedleError(needle, spec.indexes.match ?? {})).toBeUndefined()
+    }
+  })
+})

packages/stack/__tests__/v3-matrix/needle-for.ts

@@ -0,0 +1,26 @@
+import { matchNeedleError } from '@/schema/match-defaults'
+import type { V3_MATRIX } from './catalog'
+
+type MatrixSpec = (typeof V3_MATRIX)[keyof typeof V3_MATRIX]
+
+/**
+ * Pick a sample from a match domain that can actually be used as a `contains`
+ * needle. `sampleFor` is no good here — `TEXT_S[0]` is the empty string, which
+ * tokenizes to nothing and is rejected as unanswerable.
+ *
+ * Selection runs the production predicate rather than a length check of our
+ * own. A `sample.length >= 3` check would count UTF-16 code units where the
+ * guard counts codepoints, so an astral sample ('👍👍': 4 units, 2 codepoints)
+ * would be picked here and then thrown out by the guard, blaming the wrong
+ * line. It would also ignore a domain that raises its own `token_length`.
+ */
+export const needleFor = (spec: MatrixSpec): string => {
+  const match = spec.indexes.match ?? {}
+  const needle = spec.samples.find(
+    (sample) => typeof sample === 'string' && !matchNeedleError(sample, match),
+  )
+  if (typeof needle !== 'string') {
+    throw new Error('no searchable sample for a match domain')
+  }
+  return needle
+}

packages/stack/src/eql/v3/drizzle/codec.ts

@@ -21,6 +21,10 @@ export class EqlV3CodecError extends Error {
  * which has no top-level `c`. Checking `v` plus either carrier distinguishes an
  * envelope from a bare scalar, an array, or an unrelated object — without
  * paying a full structural validation on every decrypted row.
+ *
+ * The `sv` carrier must be a non-empty array: `sv[0]` is the decryption root,
+ * so `sv: []` has a ciphertext key but no ciphertext, and would reach `decrypt`
+ * as garbage.
  */
 function assertEnvelope(value: unknown, source: string): Encrypted {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -29,11 +33,14 @@ function assertEnvelope(value: unknown, source: string): Encrypted {
     )
   }
   const envelope = value as { v?: unknown; c?: unknown; sv?: unknown }
+  // A SteVec carries its root ciphertext at `sv[0].c`, so an empty or non-array
+  // `sv` carries no ciphertext at all — presence of the key is not enough.
+  const hasSteVec = Array.isArray(envelope.sv) && envelope.sv.length > 0
   const missing =
     envelope.v === undefined
       ? '"v"'
-      : envelope.c === undefined && envelope.sv === undefined
-        ? 'a ciphertext ("c", or "sv" for a SteVec document)'
+      : envelope.c === undefined && !hasSteVec
+        ? 'a ciphertext ("c", or a non-empty "sv" for a SteVec document)'
         : undefined
   if (missing) {
     throw new EqlV3CodecError(