Merge pull request #473 from cipherstash/protect-ffi-0-22-0

feat: upgrade protect-ffi to 0.23.0

Author: freshtonic

.changeset/protect-ffi-0-23-0.md

@@ -0,0 +1,21 @@
+---
+"@cipherstash/protect": major
+"@cipherstash/stack": minor
+"@cipherstash/schema": major
+"@cipherstash/protect-dynamodb": patch
+"@cipherstash/prisma-next": minor
+"stash": minor
+---
+
+Upgrade `@cipherstash/protect-ffi` to `0.23.0` and the bundled CipherStash EQL extension to `eql-2.3.1`.
+
+Breaking upstream changes adopted in this release:
+
+- **Encrypt-config schema version**: `buildEncryptConfig` now emits `{ v: 1, ... }` (was `{ v: 2, ... }`). protect-ffi `0.22.0` started validating this field and rejects any value other than `1` with the new `UNSUPPORTED_CONFIG_VERSION` error code.
+- **Storage and query payloads are now distinct types** (protect-ffi `0.23.0`): the previously-conflated `Encrypted` type splits into `Encrypted` (storage-only, `c` required) and a new `EncryptedQuery` (search terms — scalar `unique`/`match`/`ore` lookups and `ste_vec_selector` JSON path queries; no `c`). JSON containment queries (`ste_vec_term`) still return a storage-shaped `Encrypted` payload. `encryptQuery` / `encryptQueryBulk` now return `Encrypted | EncryptedQuery`, and the stack's `EncryptedSearchTerm` / `EncryptedQueryResult` unions widen to match. `decrypt` rejects query payloads at the type level. The DynamoDB `SearchTermsOperation` narrows via `'hm' in term` rather than `term.hm`.
+- **SteVec encoding default flipped**: protect-ffi's default `mode` for `ste_vec` indexes changed from `compat` to `standard`. The two encodings are not cross-compatible. Existing JSON-searchable data that was indexed under `compat` will need to be re-encrypted to be queryable. The stack adopts the new `standard` default — there is no longer a way to pin `compat` from the SDK.
+- **EQL extension bumped to `eql-2.3.1`**: the new SteVec `standard` encoding requires matching support in the database EQL extension. The CLI's bundled SQL (`packages/cli/src/sql/*.sql`) and the `@cipherstash/prisma-next` install bundle (`migrations/20260601T0000_install_eql_bundle/ops.json` + `eql-install.generated.ts`) are updated to `eql-2.3.1`. Databases installed with an older EQL extension must be reinstalled (`stash db install`) before containment / contained-by queries against SteVec columns will work. `eql-2.3.1` ships the `_encrypted_check_c` fix for SteVec storage payloads ([cipherstash/encrypt-query-language#232](https://github.com/cipherstash/encrypt-query-language/issues/232)).
+- **New error codes**: `ProtectErrorCode` (re-exported from `@cipherstash/protect-ffi`) gains `MATCH_REQUIRES_TEXT` and `UNSUPPORTED_CONFIG_VERSION`. Exhaustive switches over `ProtectErrorCode` will need additional cases.
+- **`match` index validation**: protect-ffi now rejects `match` indexes on columns whose `cast_as` is not text-family (`'text'` / `'string'`) with `MATCH_REQUIRES_TEXT`. The stack's `freeTextSearch()` builder is unaffected because it only targets string-typed columns.
+- **`Encrypted` ciphertext shape**: protect-ffi's `Encrypted` type is now a discriminated union keyed on `k` (`'ct'` for scalars, `'sv'` for SteVec). SteVec storage payloads now place the root document ciphertext at `sv[0].c`. The stack's `isEncryptedPayload` runtime check continues to work because storage payloads still carry `c` (scalar) or `sv` (SteVec). The DynamoDB helpers (`toEncryptedDynamoItem`, `SearchTermsOperation`) now narrow on `k` before reading variant-only fields.
+- **Config-validation error message wording**: error messages for config-validation failures now come from upstream `ConfigError`. `ProtectError.code` values are preserved; consumers that string-match on `err.message` for config-validation errors must update.

.github/workflows/tests.yml

@@ -15,11 +15,11 @@ jobs:
 
     # Postgres + EQL for the integration tests. Official EQL image —
     # PostgreSQL 17 with EQL pre-installed via /docker-entrypoint-initdb.d.
-    # Pinned to eql-2.2.1 to match the EQL payload format the code emits
-    # (protect-ffi 0.21.x); bump in lockstep with the protect-ffi upgrade.
+    # Pinned to eql-2.3.1 to match the EQL payload format the code emits
+    # (protect-ffi 0.23.x); bump in lockstep with the protect-ffi upgrade.
     services:
       postgres:
-        image: ghcr.io/cipherstash/postgres-eql:17-2.2.1
+        image: ghcr.io/cipherstash/postgres-eql:17-2.3.1
         env:
           POSTGRES_USER: cipherstash
           POSTGRES_PASSWORD: password

examples/prisma/migrations/cipherstash/20260601T0000_install_eql_bundle/migration.json

@@ -116,5 +116,5 @@
     "applied": [],
     "plannerVersion": "2.0.0"
   },
-  "migrationHash": "sha256:9b44ccc4d0753b364e546297857dcd8dd1ea0c16d2d09579ddb3c8d0e5fc3115"
+  "migrationHash": "sha256:76923a92561cdad65c64088ce999bf7afe853b80aac0b787b0d271b0e623abbc"
 }

examples/prisma/migrations/cipherstash/20260601T0000_install_eql_bundle/ops.json

@@ -2,7 +2,7 @@ services:
   postgres: &postgres
     # PostgreSQL 17 with CipherStash EQL pre-installed (official image).
     # Pinned by tag — bump in lockstep with the EQL version the code targets.
-    image: ghcr.io/cipherstash/postgres-eql:17-2.2.1
+    image: ghcr.io/cipherstash/postgres-eql:17-2.3.1
     environment:
       PGPORT: 5432
       POSTGRES_DB: "cipherstash"

local/docker-compose.yml

@@ -4,7 +4,7 @@ import pg from 'pg'
 
 // EQL release, pinned to match the EQL payload format this package emits.
 // Bump in lockstep with @cipherstash/protect-ffi.
-const EQL_VERSION = 'eql-2.2.1'
+const EQL_VERSION = 'eql-2.3.1'
 const EQL_INSTALL_URL =
   `https://github.com/cipherstash/encrypt-query-language/releases/download/${EQL_VERSION}/cipherstash-encrypt.sql`
 const EQL_INSTALL_NO_OPERATOR_FAMILY_URL =