Stash Encryption

CipherStash Stack - Encryption

Comprehensive guide for implementing field-level encryption with @cipherstash/stack. Every value is encrypted with its own unique key via ZeroKMS (backed by AWS KMS). Encryption happens client-side before data leaves the application.

Encrypted columns are EQL v3 concrete Postgres domains (public.eql_v3_text_search, public.eql_v3_integer_ord, ...): each column's query capabilities are fixed by the domain type you pick in the schema, and the Encryption client (typed for an all-v3 schema set) derives precise TypeScript types from that schema — wrong-typed plaintext is a compile error, not a runtime surprise.

EQL v2 is a read-compatibility path only. The v2 schema builders and the @cipherstash/stack/client subpath have been removed; decrypt / decryptModel still read stored v2 payloads so existing deployments keep working — see "Legacy: EQL v2" at the end. Author every schema and every new write with the v3 surface this skill describes.

When to Use This Skill

• Adding field-level encryption to a TypeScript/Node.js project
• Defining encrypted table schemas with the types.* domain catalog
• Encrypting and decrypting individual values or entire models
• Implementing searchable encryption (equality, free-text, range, encrypted JSON)
• Bulk encrypting/decrypting large datasets
• Implementing identity-aware encryption with JWT-based lock contexts
• Setting up multi-tenant encryption with keysets
• Rolling encryption out to a production table with live plaintext data

Quick Start

import { Encryption } from "@cipherstash/stack"
import { encryptedTable, types } from "@cipherstash/stack/v3"

const users = encryptedTable("users", {
  email: types.TextSearch("email"),
})

const client = await Encryption({ schemas: [users] })

const encrypted = await client.encrypt("secret@example.com", {
  table: users,
  column: users.email,
})
if (encrypted.failure) {
  throw new Error(encrypted.failure.message)
}

const decrypted = await client.decrypt(encrypted.data)

Installation

npm install @cipherstash/stack

Version note: npx stash init is the preferred install path — it pins every @cipherstash/* package to the versions matching your CLI release. If you install manually as above, verify what actually resolved (node -p "require('@cipherstash/stack/package.json').version"): bare dist-tag installs can lag behind a release, and stash init will warn on the version skew.

[!IMPORTANT] Exclude @cipherstash/stack from bundling — required for any project with a bundler (Next.js, webpack, esbuild, vite SSR, etc.). The package wraps a native FFI module (@cipherstash/protect-ffi) that cannot be bundled. Importing the encryption client from server code without this exclusion will fail at runtime with errors about missing native modules. Configure as soon as you install the package; do not skip this step.

Concrete configuration for the most common bundlers:

Next.js (next.config.{js,ts,mjs}):

const nextConfig = {
  serverExternalPackages: ['@cipherstash/stack', '@cipherstash/protect-ffi'],
}
export default nextConfig

(Older Next.js — pre-15 — uses experimental.serverComponentsExternalPackages with the same value.)

webpack (next/nuxt/remix/etc. that compose webpack directly):

config.externals.push('@cipherstash/stack', '@cipherstash/protect-ffi')

esbuild:

{ external: ['@cipherstash/stack', '@cipherstash/protect-ffi'] }

Vite SSR:

ssr: { external: ['@cipherstash/stack', '@cipherstash/protect-ffi'] }

If you skip this step, you'll see runtime errors like Cannot find module '@cipherstash/protect-ffi-darwin-arm64' or dlopen failed once the bundler tries to inline the native binding.

Configuration

Local Development (preferred: stash auth login)

No environment variables are needed for local development:

npx stash init        # agent-assisted setup: auth + schema + database, end to end
# or, if the project is already set up:
npx stash auth login  # device code flow; token saved to ~/.cipherstash/auth.json

npx stash init is the assisted flow — it authenticates, builds the encryption schema with you, generates the client file, and wires the database. For an already-initialized project, npx stash auth login alone authenticates the machine; the SDK and CLI pick up the saved profile automatically. Sign up at cipherstash.com/signup first.

Agents can drive the login too: npx stash auth login --json --region <slug> emits the verification URL as data — run it in the background, relay the URL to the human, and the flow completes when they approve in a browser. The event contract and the operational loop are in the stash-cli skill's Authentication section.

CI and Production (environment variables)

Deployed environments and CI use machine credentials via environment variables (set in your hosting platform or pipeline secrets — not committed .env):

CS_WORKSPACE_CRN=crn:ap-southeast-2.aws:your-workspace-id
CS_CLIENT_ID=your-client-id
CS_CLIENT_KEY=your-client-key
CS_CLIENT_ACCESS_KEY=your-access-key

Mint all four from your device session with npx stash env --name <name> — no dashboard copy-paste. It creates a fresh ZeroKMS client plus a member-role access key (shown exactly once; the CLI cannot mint admin keys) and prints the block above, ready to pipe into your platform's secret store. CS_CLIENT_KEY and CS_CLIENT_ACCESS_KEY are secrets — never commit them. Also the path for runtimes that can't read ~/.cipherstash — e.g. @cipherstash/stack/wasm-inline on Supabase Edge Functions (containerised even in local dev) or Cloudflare Workers. See the stash-cli skill for flags (--write, --json).

When both are present, the CS_* variables take precedence over the saved profile.

Programmatic Config

const client = await Encryption({
  schemas: [users],
  config: {
    workspaceCrn: "crn:ap-southeast-2.aws:your-workspace-id",
    clientId: "your-client-id",
    clientKey: "your-client-key",
    accessKey: "your-access-key",
    keyset: { name: "my-keyset" }, // optional: multi-tenant isolation
  },
})

If config is omitted, the client resolves credentials automatically: CS_* environment variables when set (CI/production), otherwise the local stash auth login profile (development).

Logging

Logging is enabled by default at the error level. Configure the log level with the STASH_STACK_LOG environment variable:

STASH_STACK_LOG=error  # debug | info | error (default: error)

When STASH_STACK_LOG is not set, the SDK defaults to error (errors only).

The SDK never logs plaintext data.

Subpath Exports

Schema Definition

Define which tables and columns to encrypt with encryptedTable and the types namespace. Every encrypted column is a concrete Postgres domain whose query capabilities are fixed by the type — there is no chainable capability tuner; every domain is fully described by its types.* factory.

import { encryptedTable, types } from "@cipherstash/stack/eql/v3"
// (also re-exported from "@cipherstash/stack/v3")

const users = encryptedTable("users", {
  email: types.TextSearch("email"),       // equality + order/range + free-text
  username: types.TextEq("username"),     // equality only
  balance: types.BigintOrd("balance"),    // equality + order/range
  lastLogin: types.TimestampOrd("last_login"),
  active: types.Boolean("active"),        // storage only — encrypt/decrypt, no queries
  notes: types.Text("notes"),             // storage only
})

const events = encryptedTable("events", {
  metadata: types.Json("metadata"),       // encrypted JSONB: containment + selectors
})

The returned table is also a column accessor (users.email). The JS property name and the DB column name may differ: lastLogin: types.TimestampOrd("last_login") reads/writes the lastLogin property on models but targets the last_login column in the database.

The types Namespace

Each factory in types maps 1:1 to a Postgres domain named public.eql_v3_<name>. The naming rule: strip the eql_v3_ prefix and PascalCase each underscore-separated segment. So types.TextSearch builds a public.eql_v3_text_search column, types.IntegerOrd builds public.eql_v3_integer_ord, and types.Timestamp builds public.eql_v3_timestamp. One exception: types.Json builds public.eql_v3_json_search, not eql_v3_json (and its query-operand domain is eql_v3.query_json, not query_json_search).

The capability matrix

Picking the wrong factory is silent at authoring time. There is no type error and no runtime warning — the predicate you wanted simply will not run, and you find out when a query errors or returns nothing. Look your type up here before writing the column.

That is the whole surface — 40 factories, no others. Three things the table is trying to make unmissable:

1. A bare factory name is storage-only. types.Double encrypts and decrypts and answers nothing. If you want to compare it, you wanted types.DoubleOrd; if you want ORE blocks specifically, types.DoubleOrdOre. The same holds for every family.
2. On the numeric and temporal families, one ordering index serves everything. Their ordering term is injective (distinct plaintexts give distinct terms), so = rides it — there is deliberately no eq_term overload for those domains, and adding an equality index to a _ord numeric column indexes a function that does not exist. Text ordering terms are not injective, which is why text_ord / text_ord_ore / text_search carry eq_term as well.
3. Ord and OrdOre are not interchangeable. They mint different, non-cross-comparable terms (eql_v3.ord_term vs eql_v3.ord_term_ore), so you cannot switch one for the other without re-encrypting the column.

ORDER BY needs the extractor form (ORDER BY eql_v3.ord_term(col)); the ORM integrations emit it for you. The CREATE INDEX statements behind the "What to index" column are in the stash-indexing skill, and the raw-SQL predicate forms with their eql_v3.query_* operand casts are in stash-postgres.

Where these objects live

Three schemas, and knowing which is which resolves most "function does not exist" errors:

So a single encrypted comparison touches all three: a public column, cast against an eql_v3 query domain, comparing eql_v3_internal term types. That is also why the Supabase role grants cover eql_v3 and eql_v3_internal — granting only the first leaves anon / authenticated / service_role unable to execute the internal term operators the public ones inline to. The eql_v3 schemas are dropped and recreated by every install; public is not, which is why your column domains survive a reinstall.

Capability suffixes:

Ord vs OrdOre — prefer Ord. The OrdOre domains are backed by an ORE operator class the installer creates with CREATE OPERATOR CLASS, which is superuser-gated in stock PostgreSQL. Platform support varies and is not a blanket managed-Postgres rule: AWS RDS and Aurora allow it (their admin role clears the gate despite rolsuper = f); cloud-hosted Supabase is the one confirmed platform that refuses it.

Where the install role cannot create the class, the bundle skips it and adds an always-raising eql_ore_unavailable CHECK to every _ord_ore domain, so every write to such a column fails loudly rather than producing an index that silently never engages. On those databases an OrdOre column is unusable, not merely unindexed — which is why the matrix marks it ⛔ rather than ⚠️.

Don't guess which case you are in — ask: stash eql preflight predicts it before you install (the ORE operator class row), and stash eql status / stash eql verify report it afterwards. Ord is OPE-backed, binds PostgreSQL's native bytea btree operator class, and needs no privileges anywhere.

The two flavours mint different, non-cross-comparable terms (Ord/Search extract via eql_v3.ord_term; OrdOre via eql_v3.ord_term_ore), so switching between them means re-encrypting the column.

Domain families and plaintext types:

Examples: types.Text("notes") (storage only), types.TextEq("username"), types.BigintOrd("balance"), types.TimestampOrdOre("created_at"), types.Boolean("active"), types.Json("metadata").

The match index on Match/Search columns is always emitted with the default configuration (trigram tokenizer, downcased) — there is no per-column tuning in v3. Search needles must be at least 3 characters; shorter needles tokenize to nothing and are rejected.

Type Inference

import type { InferPlaintext, InferEncrypted } from "@cipherstash/stack/eql/v3"

type UserPlaintext = InferPlaintext<typeof users>
// { email: string; lastLogin: Date; balance: bigint; ... }

type UserEncrypted = InferEncrypted<typeof users>
// { email: Encrypted; lastLogin: Encrypted; balance: Encrypted; ... }

V3ModelInput, V3EncryptedModel, and V3DecryptedModel (same subpath) are the model-shape helpers the typed client uses: schema-column keys are pinned to the column's plaintext type (nullable fields stay nullable), non-schema keys pass through unchanged.

Database Setup

Install the EQL v3 SQL with the stash CLI (v3 is the default):

stash eql install

# Supabase targets: add --supabase to apply role grants
stash eql install --supabase

EQL v3 ships one SQL bundle for every target. For Supabase, pass --supabase to apply grants on eql_v3 and eql_v3_internal. For a Drizzle migration, use stash eql migration --drizzle; the old v2 install flags were removed.

In migrations, declare each encrypted column as its domain type:

CREATE TABLE users (
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email public.eql_v3_text_search,
  last_login public.eql_v3_timestamp_ord,
  balance public.eql_v3_bigint_ord
);

Client Initialization: Encryption

Encryption from @cipherstash/stack accepts concrete EQL v3 tables and returns EncryptionClient<S>, whose method signatures are derived from those schemas. Wrong-typed plaintext is rejected at compile time, and query methods only accept queryable columns with queryType constrained to the column's capabilities:

import { Encryption } from "@cipherstash/stack"
import { encryptedTable, types } from "@cipherstash/stack/v3"

const users = encryptedTable("users", {
  email: types.TextSearch("email"),
  lastLogin: types.TimestampOrd("last_login"),
  balance: types.BigintEq("balance"),
})

const client = await Encryption({ schemas: [users] })

• The wire format is always EQL v3; config.eqlVersion does not exist.
• Encryption() throws on init error (bad credentials, missing config, invalid keyset UUID). At least one schema is required.
• A loose object or legacy v2 table is rejected at runtime as well as by TypeScript.
• schemas takes any non-empty array of v3 tables — a shared export const schemas: AnyV3Table[], a ReadonlyArray, one built at runtime. It does not have to be an array literal. Writing Encryption({ schemas: [] }) is a compile error, but an array typed AnyV3Table[] that is empty at runtime compiles and throws on init instead.
• To name the client's type, use EncryptionClient<S> from @cipherstash/stack/v3:

import { type AnyV3Table, Encryption, type EncryptionClient, encryptedTable, types } from "@cipherstash/stack/v3"

const users = encryptedTable("users", { email: types.TextSearch("email") })

// A named schema tuple keeps per-column typing.
let client: EncryptionClient<readonly [typeof users]>
client = await Encryption({ schemas: [users] })

// Code that is generic over its schemas keeps the typed surface too.
function withClient(c: EncryptionClient<readonly AnyV3Table[]>) { /* … */ }

// Error handling
try {
  const client = await Encryption({ schemas: [users] })
} catch (error) {
  console.error("Init failed:", error.message)
}

Encrypt and Decrypt Single Values

Plaintext is pinned to the column's domain type:

await client.encrypt("alice@example.com", { table: users, column: users.email })  // string ✓
await client.encrypt(new Date(), { table: users, column: users.lastLogin })       // Date ✓
// client.encrypt(42, { table: users, column: users.email })  // ✗ compile error

const encrypted = await client.encrypt("hello@example.com", {
  table: users,
  column: users.email,
})

if (encrypted.failure) {
  throw new Error(encrypted.failure.message)
}
console.log(encrypted.data) // Encrypted payload (opaque object)

// Decrypt
const decrypted = await client.decrypt(encrypted.data)

if (!decrypted.failure) {
  console.log(decrypted.data) // "hello@example.com"
}

decrypt of a single value cannot be strongly typed — TypeScript cannot know which column a runtime payload came from, so the result is the whole plaintext union. All plaintext values passed to encrypt must be non-null; null handling is managed at the model level by encryptModel and decryptModel.

decrypt / bulkDecrypt hand back date columns as strings, not Date. Reconstruction is driven by the table's cast_as, and only the model path is given a table — so the same stored value comes back as a Date from decryptModel(row, table) and as its stored ISO string from decrypt(payload). Nothing warns: the raw path's declared type is the plaintext union, which includes string. Comparing two ISO strings orders correctly, so this survives review and breaks later on .getTime() or date arithmetic. Use the model helpers when you want the column's declared plaintext type, or rebuild at the call site (new Date(value)). Same on the WASM entry, and same for the one-arg decryptModel(row) / bulkDecryptModels(rows) forms, which take no table.

Model Operations

Encrypt or decrypt an entire object. Only fields matching your schema are encrypted; other fields pass through unchanged, and schema fields are validated against their inferred plaintext type at compile time.

const enc = await client.encryptModel(
  { id: "u1", email: "alice@example.com", lastLogin: new Date(), balance: 100n },
  users,
)
if (!enc.failure) {
  // enc.data.email is Encrypted; enc.data.id stays string

  const dec = await client.decryptModel(enc.data, users)
  if (!dec.failure) {
    dec.data.email     // string
    dec.data.lastLogin // Date — reconstructed on decrypt
    dec.data.balance   // bigint
    dec.data.id        // string — non-schema fields pass through
  }
}

Typed-client model notes:

• decryptModel / bulkDecryptModels take the table as a second argument and return a chainable AuditableDecryptModelOperation — await it for the Result, or chain .audit({ metadata }) / .withLockContext(lockContext) first. A lock context may instead be passed as the optional third argument; use one form or the other, not both (chaining .withLockContext() onto a decrypt that already took a positional lock context throws).
• Date columns are reconstructed to real Date instances by decryptModel(row, table) / bulkDecryptModels(rows, table) — the table-taking forms, and only those (see the raw-path note above); bigint columns round-trip as native bigint on every path. A stored value that does not parse as a date (a legacy non-ISO string, say) is handed back unchanged rather than as an Invalid Date, even though the declared type is Date — guard with instanceof Date before calling Date methods on a column whose stored values you don't control.
• Nullable schema fields stay nullable through the round trip.

Bulk Operations

All bulk methods make a single call to ZeroKMS regardless of record count, while still using a unique key per value.

Bulk Encrypt / Decrypt Models

const userModels = [
  { id: "1", email: "alice@example.com", lastLogin: new Date(), balance: 1n },
  { id: "2", email: "bob@example.com", lastLogin: new Date(), balance: 2n },
]

const encrypted = await client.bulkEncryptModels(userModels, users)
if (encrypted.failure) throw new Error(encrypted.failure.message)

const decrypted = await client.bulkDecryptModels(encrypted.data, users)

Bulk Encrypt / Decrypt (Raw Values)

These two work on raw value arrays rather than models. bulkEncrypt is typed like encrypt — { table, column } pins every plaintext to that column's domain — while bulkDecrypt takes the payloads alone, so it resolves to the plaintext union and does no Date reconstruction: a types.Timestamp column read this way is the stored ISO string, where bulkDecryptModels(rows, table) gives you a Date:

const plaintexts = [
  { id: "u1", plaintext: "alice@example.com" },
  { id: "u2", plaintext: "bob@example.com" },
]

const encrypted = await client.bulkEncrypt(plaintexts, {
  column: users.email,
  table: users,
})
if (encrypted.failure) throw new Error(encrypted.failure.message)
// encrypted.data = [{ id: "u1", data: EncryptedPayload }, ...]

const decrypted = await client.bulkDecrypt(encrypted.data)
if (decrypted.failure) throw new Error(decrypted.failure.message)
// Per-item error handling:
for (const item of decrypted.data) {
  if ("data" in item) {
    console.log(`${item.id}: ${item.data}`)
  } else {
    console.error(`${item.id} failed: ${item.error}`)
  }
}

On the WASM entry (@cipherstash/stack/wasm-inline), the batch shape differs — do not copy the shape above onto the edge. The { data } | { failure } Result is the same, but there are no { id, plaintext } envelopes: each entry carries its own table and column, and the payload is a plain index-aligned array.

[!IMPORTANT] The client below is a different client from the one used everywhere else in this skill. The edge entry has its own Encryption factory — the native Encryption client's bulkEncrypt takes (plaintexts, { table, column }) and will fail at runtime if given the per-item shape below. Construct the WASM client explicitly:

[!NOTE] The schema, unlike the client, IS shareable between entries. encryptedTable and types are imported from the WASM entry below only because this example's own runtime is the edge; a table authored from @cipherstash/stack/eql/v3 or @cipherstash/stack/v3 works here just as well, and in the other direction too. One schema.ts can serve a Node server and an Edge Function.

On older @cipherstash/stack versions it could not: the entries shipped separately-emitted declarations of the column classes, which carry private fields, so TypeScript compared them nominally and each entry rejected the other's schema (Types have separate declarations of a private property 'columnName'). It always worked at runtime, which made as any the tempting fix — if you hit that diagnostic, upgrade rather than assert. See the stash-edge skill.

// Deno / Workers / Supabase Edge Functions — note the import path
import { Encryption, encryptedTable, types } from "@cipherstash/stack/wasm-inline"

const users = encryptedTable("users", { email: types.TextEq("email") })

const client = await Encryption({
  schemas: [users],
  config: {
    workspaceCrn: Deno.env.get("CS_WORKSPACE_CRN")!,
    accessKey: Deno.env.get("CS_CLIENT_ACCESS_KEY")!,
    clientId: Deno.env.get("CS_CLIENT_ID")!,
    clientKey: Deno.env.get("CS_CLIENT_KEY")!,
  },
})

const encrypted = await client.bulkEncrypt([
  { plaintext: "alice@example.com", table: users, column: users.email },
  { plaintext: "hello", table: users, column: users.bio },
])
if (encrypted.failure) throw new Error(encrypted.failure.message)
// encrypted.data = [EncryptedPayload, EncryptedPayload] — same order as the input

const decrypted = await client.bulkDecrypt(rows.map((r) => r.email))
if (decrypted.failure) throw new Error(decrypted.failure.message)
// one ZeroKMS round trip for the whole list, not one per row

null / undefined entries yield null at the same index without reaching ZeroKMS. Because each entry names its own column, one call can cover several columns across many rows. When items fail to decrypt, failure.message names every failing index.

The model helpers are available on the WASM entry too: encryptModel(model, table), decryptModel(model, table), bulkEncryptModels(models, table), bulkDecryptModels(models, table). They run the same schema walk as the native client — declared columns are encrypted (matched by JS property name; nested fields via the column's dotted path), everything else passes through, null/undefined fields are preserved without reaching ZeroKMS, and the caller's model is never mutated — and a call that touches at least one field is one ZeroKMS round trip no matter how many fields or models it covers (an empty batch, or one whose models carry no schema fields, is short-circuited and makes zero calls). table must be one the client was built with (Encryption({ schemas })), else the call fails, as on the native client. types.Date / types.Timestamp columns round-trip Date → Date (on the wire they travel as ISO strings); because matching is by JS property name, a row keyed by raw DB column names (e.g. a raw SELECT returning created_on) still decrypts, but its date fields come back as ISO strings — key your models by the schema's property names. Differences from the native typed client: every method returns a plain Promise of the { data } | { failure } Result (no .audit() chaining), and there is no lock-context argument — a known gap (#797), not a different mechanism. config.authStrategy decides who the client is; it does not bind values to the user (a lock context gates retrieval of a value's data key by a claim — stash-auth is canonical). Values written on the edge therefore carry no identity condition, and the edge cannot read values the native entry wrote under a lock context. Decrypt failures name every failing field: bulkDecryptModels prefixes the model index ([model 1] profile.ssn), decryptModel names the field alone (profile.ssn).

const row = await client.encryptModel({ id: 1, email: "alice@example.com" }, users)
if (row.failure) throw new Error(row.failure.message)
// row.data = { id: 1, email: <EQL envelope> } — only schema columns encrypted

const back = await client.bulkDecryptModels(encryptedRows, users)
if (back.failure) throw new Error(back.failure.message)
// back.data = plaintext models, index-aligned with the input

Searchable Encryption

Encrypt query terms with encryptQuery so you can search encrypted data in PostgreSQL. On the typed client, encryptQuery only accepts queryable columns (storage-only columns are rejected at compile time) and constrains queryType to the column's capabilities.

// Equality query
const eqQuery = await client.encryptQuery("alice@example.com", {
  column: users.email,
  table: users,
  queryType: "equality",
})

// Free-text search (substring/token match)
const matchQuery = await client.encryptQuery("alice", {
  column: users.email,
  table: users,
  queryType: "freeTextSearch",
})

// Order and range
const rangeQuery = await client.encryptQuery(new Date("2026-01-01"), {
  column: users.lastLogin,
  table: users,
  queryType: "orderAndRange",
})

Query-Type Inference Gotcha on types.TextSearch

A TextSearch column carries all three indexes, and encryptQuery with no explicit queryType builds an equality term, not a free-text match (index inference priority: unique > match > ore). A substring like "joh" then matches nothing. Pass queryType: 'freeTextSearch' explicitly for substring/token search:

// equality (default): exact value only
await client.encryptQuery("john@example.com", { column: users.email, table: users })

// free-text match: substring/token search
await client.encryptQuery("joh", {
  column: users.email,
  table: users,
  queryType: "freeTextSearch",
})

Free-Text Search Semantics

Encrypted free-text search is fuzzy bloom-filter token matching, not SQL pattern matching:

• The needle blooms to its own trigrams; a row matches when the stored value's bloom contains all of them. Case-insensitive; order- and multiplicity-insensitive.
• One-sided: a match may be a false positive; a non-match never is.
• Needles must be at least 3 characters (the default trigram length) — shorter needles bloom to nothing and are rejected rather than silently matching every row.
• In the Drizzle and Supabase v3 integrations the operator is matches — the adapters expose free-text search as matches, not like/ilike (the Supabase adapter keeps a deprecated like/ilike shim that delegates to matches with a warning). Don't pass % wildcards.

Query Result Formatting (returnType)

By default encryptQuery returns an Encrypted object (the raw EQL JSON payload). Use returnType to change the output format:

const term = await client.encryptQuery("alice@example.com", {
  column: users.email,
  table: users,
  queryType: "equality",
  returnType: "composite-literal",
})
// term.data is a string

Each term in a batch can have its own returnType.

Batch Query Encryption

Encrypt multiple query terms in one ZeroKMS call (the per-term columns are heterogeneous, so the batch form takes untyped ScalarQueryTerms):

const terms = [
  { value: "alice@example.com", column: users.email, table: users, queryType: "equality" as const },
  { value: "bob", column: users.email, table: users, queryType: "freeTextSearch" as const },
]

const results = await client.encryptQuery(terms)
// results.data = [EncryptedPayload, EncryptedPayload]

All values in the array must be non-null.

On the Wire: Operators and Ordering

Scalar filters compare through each domain's eql_v3.* operators (col = term, col > term, ...), and ORDER BY on an encrypted column goes through the ordering extractors — eql_v3.ord_term(col) for OPE-backed (Ord/Search) domains, eql_v3.ord_term_ore(col) for OrdOre. The Drizzle v3 integration emits all of this for you (including asc/desc, which emit ORDER BY eql_v3.ord_term(col)). Over Supabase/PostgREST, the adapter's order() works on OPE-backed ordering columns (plain *_ord, text_ord, text_search) by sorting on the column's col->op term; OrdOre-flavour (*_ord_ore) domains and columns with no ordering term are rejected. See the stash-drizzle and stash-supabase skills. These same extractor expressions are also what you index — the functional-index recipes are in the stash-indexing skill. Writing the SQL by hand instead (no ORM, pg / postgres-js)? The predicate matrix, the eql_v3.query_* operand casts, and the per-driver parameter-binding rules are in the stash-postgres skill; running on Deno / Workers / Supabase Edge Functions, the stash-edge skill.

Encrypted JSON (types.Json)

A types.Json("metadata") column encrypts a whole JSON document to a public.eql_v3_json_search value. The plaintext is a JsonDocument: an object, an array, or null — NOT a bare top-level scalar (protect-ffi rejects a top-level string/number/boolean; a scalar belongs in a scalar domain like types.TextEq or types.IntegerEq). Nested scalars are fully supported.

types.Json carries no equality or ordering capability — eq / gt / asc on it throw. It supports two query patterns: containment and JSONPath selectors.

Containment (exact, @>)

Pass a sub-object or sub-array to encryptQuery with queryType: 'searchableJson'; it matches documents that contain the needle with jsonb @> semantics — exact containment, no false positives. Array containment is a subset test regardless of element position: { roles: ['admin'] } matches any document whose roles array includes admin.

const events = encryptedTable("events", { metadata: types.Json("metadata") })

// containment: object needle
await client.encryptQuery({ roles: ["admin"] }, { column: events.metadata, table: events })

The Drizzle and Supabase adapters reject an empty-object needle (jsonb {} ⊆ anything — it would silently match every row); core client.encryptQuery does not enforce this, so guard against empty needles yourself when composing raw SQL.