@cipherstash/stack 1.0.0-rc.0 → 1.0.0-rc.2

package/README.md

@@ -6,7 +6,7 @@ The all-in-one TypeScript SDK for the CipherStash data security stack.
 [![License: MIT](https://img.shields.io/npm/l/@cipherstash/stack.svg?style=for-the-badge&labelColor=000000)](https://github.com/cipherstash/stack/blob/main/LICENSE.md)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-blue?style=for-the-badge&labelColor=000000)](https://www.typescriptlang.org/)
 
---
+---
 
 ## Table of Contents
 
@@ -16,17 +16,18 @@ The all-in-one TypeScript SDK for the CipherStash data security stack.
 - [Schema Definition](#schema-definition)
 - [Encryption and Decryption](#encryption-and-decryption)
 - [Searchable Encryption](#searchable-encryption)
-- [Identity-Aware Encryption](#identity-aware-encryption)
+- [Authentication](#authentication)
+- [Identity-Aware Encryption](#identity-aware-encryption-lock-contexts)
 - [CLI Reference](#cli-reference)
 - [Configuration](#configuration)
 - [Error Handling](#error-handling)
 - [API Reference](#api-reference)
 - [Subpath Exports](#subpath-exports)
-- [Migration from @cipherstash/protect](#migration-from-cipherstashprotect)
+- [Legacy: EQL v2](#legacy-eql-v2)
 - [Requirements](#requirements)
 - [License](#license)
 
---
+---
 
 ## Install
 
@@ -53,17 +54,19 @@ The wizard will authenticate you, walk you through choosing a database connectio
 
 ### 2. Encrypt and decrypt
 
+Define a table with concrete EQL v3 column types, build the typed client, and encrypt:
+
 ```typescript
-import { Encryption } from "@cipherstash/stack"
-import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+import { EncryptionV3 } from "@cipherstash/stack/v3"
+import { encryptedTable, types } from "@cipherstash/stack/eql/v3"
 
-// Define a schema
+// Define a schema — the column type fixes its query capabilities
 const users = encryptedTable("users", {
-  email: encryptedColumn("email").equality().freeTextSearch(),
+  email: types.TextSearch("email"), // equality + order/range + free-text search
 })
 
-// Create a client
-const client = await Encryption({ schemas: [users] })
+// Create a typed client
+const client = await EncryptionV3({ schemas: [users] })
 
 // Encrypt a value
 const encrypted = await client.encrypt("hello@example.com", {
@@ -71,114 +74,169 @@ const encrypted = await client.encrypt("hello@example.com", {
   table: users,
 })
 
+// Every operation returns `{ data } | { failure }`. Narrow on `.failure` and
+// return/throw before reading `.data` — the failure branch has no `data`.
 if (encrypted.failure) {
-  console.error("Encryption failed:", encrypted.failure.message)
-} else {
-  console.log("Encrypted payload:", encrypted.data)
+  throw new Error(`Encryption failed: ${encrypted.failure.message}`)
 }
+console.log("Encrypted payload:", encrypted.data)
 
 // Decrypt the value
 const decrypted = await client.decrypt(encrypted.data)
-
 if (decrypted.failure) {
-  console.error("Decryption failed:", decrypted.failure.message)
-} else {
-  console.log("Plaintext:", decrypted.data) // "hello@example.com"
+  throw new Error(`Decryption failed: ${decrypted.failure.message}`)
 }
+console.log("Plaintext:", decrypted.data) // "hello@example.com"
 ```
 
+The client is typed from your schemas: passing the wrong plaintext type for a column (`client.encrypt(42, { column: users.email, ... })`) is a compile error.
+
 ## Features
 
 - **Field-level encryption** - Every value encrypted with its own unique key via [ZeroKMS](https://cipherstash.com/products/zerokms), backed by AWS KMS.
-- **Searchable encryption** - Exact match, free-text search, order/range queries, and encrypted JSONB queries in PostgreSQL.
+- **Searchable encryption** - Exact match, free-text search, order/range queries, and encrypted JSON queries in PostgreSQL, driven by concrete EQL v3 column types.
+- **Type-safe by construction** - Each encrypted column is a concrete Postgres domain; its query capabilities are fixed by the type you pick and enforced at compile time by the typed client.
 - **Bulk operations** - Encrypt or decrypt thousands of values in a single ZeroKMS call (`bulkEncrypt`, `bulkDecrypt`, `bulkEncryptModels`, `bulkDecryptModels`).
-- **Identity-aware encryption** - Tie encryption to a user's JWT via `LockContext`, so only that user can decrypt.
+- **Identity-aware encryption** - Tie encryption to a user's JWT via `OidcFederationStrategy` and `.withLockContext()`, so only that user can decrypt.
 - **CLI (`stash`)** - Initialize projects and set up encryption from the terminal.
 - **TypeScript-first** - Strongly typed schemas, results, and model operations with full generics support.
 
 ## Schema Definition
 
-Define which tables and columns to encrypt using `encryptedTable` and `encryptedColumn` from `@cipherstash/stack/schema`.
+Define which tables and columns to encrypt using `encryptedTable` and the `types` namespace from `@cipherstash/stack/eql/v3`. Each factory in `types` maps 1:1 to a **concrete Postgres domain** named `public.eql_v3_<name>` — the naming rule is: 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`.
+
+There are **no chainable capability methods** — the concrete type fully describes what a column can do.
 
 ```typescript
-import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+import { encryptedTable, types } from "@cipherstash/stack/eql/v3"
 
 const users = encryptedTable("users", {
-  email: encryptedColumn("email")
-    .equality()         // exact-match queries
-    .freeTextSearch()   // full-text search queries
-    .orderAndRange(),   // sorting and range queries
-})
-
-const documents = encryptedTable("documents", {
-  metadata: encryptedColumn("metadata")
-    .searchableJson(),  // encrypted JSONB queries (JSONPath + containment)
+  email: types.TextSearch("email"),    // equality + order/range + free-text search
+  age: types.IntegerOrd("age"),        // equality + order/range
+  balance: types.Bigint("balance"),    // storage only — encrypt/decrypt, no queries
+  metadata: types.Json("metadata"),    // encrypted JSON: containment + JSONPath selectors
 })
 ```
 
-### Index Types
+The returned table is also a column accessor (`users.email`). The JS property name and the DB column name may differ: `createdOn: types.Timestamp("created_at")` reads and writes the `createdOn` property on models but targets the `created_at` column in the database.
+
+### Capability Suffixes
+
+The suffix on the type name encodes the query capability:
+
+| Suffix | Capabilities | Query types |
+|---|---|---|
+| _(none)_ | Storage only — encrypt/decrypt, no queries | — |
+| `Eq` | Equality | `'equality'` |
+| `Ord` | Equality + ordering/range (OPE-backed) | `'equality'`, `'orderAndRange'` |
+| `OrdOre` | Equality + ordering/range (block-ORE-backed — the ORE operator class is superuser-only and unavailable on managed Postgres such as Supabase) | `'equality'`, `'orderAndRange'` |
+| `Match` (text only) | Free-text search only | `'freeTextSearch'` |
+| `Search` (text only, as `TextSearch`) | Equality + ordering/range + free-text | all three |
+| `Json` | Encrypted JSON containment + JSONPath selector queries | `'searchableJson'` |
+
+Prefer the plain `Ord` domains unless you know your database supports the ORE operator class.
+
+### Domain Families and Plaintext Types
 
-| Method | Purpose | Query Type |
-|----|-----|------|
-| `.equality()` | Exact match lookups | `'equality'` |
-| `.freeTextSearch()` | Full-text / fuzzy search | `'freeTextSearch'` |
-| `.orderAndRange()` | Sorting, comparison, range queries | `'orderAndRange'` |
-| `.searchableJson()` | Encrypted JSONB path and containment queries | `'searchableJson'` |
-| `.dataType(cast)` | Set the plaintext data type (`'string'`, `'number'`, `'boolean'`, `'date'`, `'bigint'`, `'json'`) | N/A |
+| Family | Factories | Plaintext (TypeScript) type |
+|---|---|---|
+| `Integer`, `Smallint`, `Numeric`, `Real`, `Double` | base, `Eq`, `Ord`, `OrdOre` | `number` |
+| `Bigint` | base, `Eq`, `Ord`, `OrdOre` | `bigint` (native JS bigint, full i64 range) |
+| `Date` | base, `Eq`, `Ord`, `OrdOre` | `Date` (calendar date; time-of-day truncated) |
+| `Timestamp` | base, `Eq`, `Ord`, `OrdOre` | `Date` (time-of-day preserved) |
+| `Text` | base, `Eq`, `Match`, `Ord`, `OrdOre`, `Search` | `string` |
+| `Boolean` | base only | `boolean` |
+| `Json` | `Json` only | a JSON *document* (object, array, or null — not a top-level scalar) |
+
+### Database Setup
+
+Install the EQL v3 SQL into your database with the stash CLI:
+
+```bash
+npx stash eql install --eql-version 3
+# On Supabase, add --supabase to grant the anon/authenticated/service_role
+# roles access to the eql_v3 schemas — without it, encrypted queries fail with
+# "permission denied for schema eql_v3_internal":
+npx stash eql install --eql-version 3 --supabase
+```
 
-Methods are chainable - call as many as you need on a single column.
+In migrations, declare each encrypted column as its domain type:
+
+```sql
+CREATE TABLE users (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email public.eql_v3_text_search,
+  age public.eql_v3_integer_ord,
+  balance public.eql_v3_bigint,
+  metadata public.eql_v3_json
+);
+```
 
 ## Encryption and Decryption
 
 ### Single Values
 
 ```typescript
-// Encrypt
+// Encrypt — plaintext is pinned to the column's domain type
 const encrypted = await client.encrypt("secret@example.com", {
   column: users.email,
   table: users,
 })
 
-// Decrypt
+// Decrypt (narrow on `.failure` before reading `.data`)
+if (encrypted.failure) throw new Error(encrypted.failure.message)
 const decrypted = await client.decrypt(encrypted.data)
 ```
 
 ### Model Operations
 
-Encrypt or decrypt an entire object. Only fields matching your schema are encrypted; other fields pass through unchanged.
+Encrypt or decrypt an entire object. Only fields matching your schema are encrypted; other fields pass through unchanged. Schema fields are validated against their inferred plaintext type at compile time.
 
-The return type is **schema-aware**: fields matching the table schema are typed as `Encrypted`, while other fields retain their original types. For best results, let TypeScript infer the type parameters from the arguments:
+`decryptModel` takes the **table as a second argument** and returns the precise plaintext model: `Date` columns are reconstructed to real `Date` instances, and `bigint` columns round-trip as native `bigint`.
 
 ```typescript
-type User = { id: string; email: string; createdAt: Date }
-
 const user = {
-  id: "user_123",
-  email: "alice@example.com",  // defined in schema -> encrypted
-  createdAt: new Date(),       // not in schema -> unchanged
+  id: "user_123",                // not in schema -> passes through
+  email: "alice@example.com",    // TextSearch    -> encrypted as string
+  age: 30,                       // IntegerOrd    -> encrypted as number
+  balance: 100_000n,             // Bigint        -> encrypted as bigint
 }
 
-// Let TypeScript infer the return type from the schema
 const encryptedResult = await client.encryptModel(user, users)
-// encryptedResult.data.email    -> Encrypted
-// encryptedResult.data.id       -> string
-// encryptedResult.data.createdAt -> Date
+// encryptedResult.data.email -> Encrypted
+// encryptedResult.data.id    -> string
 
-// Decrypt a model
-const decryptedResult = await client.decryptModel(encryptedResult.data)
+if (encryptedResult.failure) throw new Error(encryptedResult.failure.message)
+const decryptedResult = await client.decryptModel(encryptedResult.data, users)
+// decryptedResult.data.email   -> string
+// decryptedResult.data.balance -> bigint
 ```
 
 ### Bulk Operations
 
 All bulk methods make a single call to ZeroKMS regardless of the number of records, while still using a unique key per value.
 
+#### Bulk Encrypt / Decrypt Models
+
+```typescript
+const userModels = [
+  { id: "1", email: "alice@example.com", age: 30, balance: 100_000n },
+  { id: "2", email: "bob@example.com", age: 41, balance: 250_000n },
+]
+
+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)
 
+`bulkEncrypt` / `bulkDecrypt` are untyped passthroughs for raw value arrays:
+
 ```typescript
 const plaintexts = [
   { id: "u1", plaintext: "alice@example.com" },
   { id: "u2", plaintext: "bob@example.com" },
-  { id: "u3", plaintext: "charlie@example.com" },
 ]
 
 const encrypted = await client.bulkEncrypt(plaintexts, {
@@ -188,7 +246,9 @@ const encrypted = await client.bulkEncrypt(plaintexts, {
 
 // encrypted.data = [{ id: "u1", data: EncryptedPayload }, ...]
 
+if (encrypted.failure) throw new Error(encrypted.failure.message)
 const decrypted = await client.bulkDecrypt(encrypted.data)
+if (decrypted.failure) throw new Error(decrypted.failure.message)
 
 // Each item has either { data: "plaintext" } or { error: "message" }
 for (const item of decrypted.data) {
@@ -200,175 +260,91 @@ for (const item of decrypted.data) {
 }
 ```
 
-#### Bulk Encrypt / Decrypt Models
-
-```typescript
-const userModels = [
-  { id: "1", email: "alice@example.com" },
-  { id: "2", email: "bob@example.com" },
-]
-
-const encrypted = await client.bulkEncryptModels(userModels, users)
-const decrypted = await client.bulkDecryptModels(encrypted.data)
-```
-
 ## Searchable Encryption
 
-Encrypt a query term so you can search encrypted data in PostgreSQL.
+Encrypt a query term so you can search encrypted data in PostgreSQL. The typed client only accepts queryable columns, and `queryType` is constrained to the column's capabilities — equality and range queries run through the domain's own SQL operators.
 
 ```typescript
-// Equality query
+// Equality
 const eqQuery = await client.encryptQuery("alice@example.com", {
   column: users.email,
   table: users,
   queryType: "equality",
 })
 
-// Free-text search
-const matchQuery = await client.encryptQuery("alice", {
+// Free-text search — queryType is REQUIRED for a match term (see gotcha below)
+const matchQuery = await client.encryptQuery("ali", {
   column: users.email,
   table: users,
   queryType: "freeTextSearch",
 })
 
 // Order and range
-const rangeQuery = await client.encryptQuery("alice@example.com", {
-  column: users.email,
+const rangeQuery = await client.encryptQuery(30, {
+  column: users.age,
   table: users,
   queryType: "orderAndRange",
 })
 ```
 
-### Searchable JSON
-
-For columns using `.searchableJson()`, the query type is auto-inferred from the plaintext:
+> **Gotcha — `TextSearch` defaults to equality.** A `TextSearch` column carries all three indexes, and `encryptQuery` with **no explicit `queryType` builds an equality term, not a free-text match**. A substring like `"joh"` then matches nothing. Always pass `queryType: 'freeTextSearch'` for substring/token search.
 
-```typescript
-// String -> JSONPath selector query
-const pathQuery = await client.encryptQuery("$.user.email", {
-  column: documents.metadata,
-  table: documents,
-})
+Free-text search is fuzzy bloom-filter token matching, surfaced as `matches` in the Drizzle and Supabase adapters — it is order- and multiplicity-insensitive and one-sided (a match may be a false positive, a non-match never is). It is not SQL `LIKE`; don't pass `%` wildcards.
 
-// Object/Array -> containment query
-const containsQuery = await client.encryptQuery({ role: "admin" }, {
-  column: documents.metadata,
-  table: documents,
-})
-```
+### Encrypted JSON
 
-### Batch Query Encryption
+A `types.Json` column encrypts a whole JSON document (an object, array, or null — not a top-level scalar) to a `public.eql_v3_json` value. Two query patterns are supported:
 
-Encrypt multiple query terms in one call:
+**Exact containment** (jsonb `@>` semantics, no false positives). Pass a sub-object or sub-array needle; array containment is a subset test regardless of element position — `{ roles: ["admin"] }` matches any document whose `roles` array includes `"admin"`:
 
 ```typescript
-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)
-```
+const events = encryptedTable("events", { metadata: types.Json("metadata") })
 
-### Query Result Formatting (`returnType`)
-
-By default `encryptQuery` returns an `Encrypted` object (the raw EQL JSON payload). Use `returnType` to change the output format:
-
-| `returnType` | Output | Use case |
-|---|---|---|
-| `'eql'` (default) | `Encrypted` object | Parameterized queries, ORMs accepting JSON |
-| `'composite-literal'` | `string` | Supabase `.eq()`, string-based APIs |
-| `'escaped-composite-literal'` | `string` | Embedding inside another string or JSON value |
-
-```typescript
-// Get a composite literal string for use with Supabase
-const term = await client.encryptQuery("alice@example.com", {
-  column: users.email,
-  table: users,
-  queryType: "equality",
-  returnType: "composite-literal",
-})
-
-// term.data is a string — use directly with .eq()
-await supabase.from("users").select().eq("email", term.data)
+const containsQuery = await client.encryptQuery(
+  { roles: ["admin"] },
+  { column: events.metadata, table: events }, // queryType inferred: 'searchableJson'
+)
 ```
 
-Each term in a batch can have its own `returnType`.
+**JSONPath selectors** — equality and ordering at a path (`$.a`, `$.a.b` dot-notation object paths):
 
-### Ordering Encrypted Data
-
-**`ORDER BY` on encrypted columns requires operator family support in the database.**
+- **Drizzle**: `ops.selector(events.metadata, "$.age")` returns comparison methods bound to the path — `eq`, `ne`, `gt`, `gte`, `lt`, `lte` (e.g. `await ops.selector(events.metadata, "$.age").gt(21)`). Its unique power over containment is *ordering* at a path; equality at a path is equivalently `contains(col, { age: 21 })`.
+- **Supabase**: `selectorEq(col, path, value)` and `selectorNe(col, path, value)`.
 
-On databases without operator families (e.g. Supabase, or when EQL is installed with `--exclude-operator-family`), sorting on encrypted columns is not currently supported — regardless of the client or ORM used. Sort application-side after decrypting the results as a workaround.
+Two semantics to know:
 
-Operator family support for Supabase is being developed in collaboration with the Supabase and CipherStash teams and will be available in a future release.
+- **`ne` includes absent paths.** A "not equal at path" query also matches rows where the path does not exist at all.
+- **Array-leaf caveat:** a scalar needle does not match an array at the path. `selectorEq("payload", "$.roles", "admin")` does *not* match `{ roles: ["admin", "analyst"] }` — use containment for membership tests.
 
-### PostgreSQL / Drizzle Integration Pattern
+`types.Json` carries no equality or ordering on the document itself, so applying `eq` / `gt` / `asc` directly to a `Json` column throws.
 
-Encrypted data is stored as an [EQL](https://github.com/cipherstash/encrypt-query-language) JSON payload. Install the EQL extension in PostgreSQL to enable searchable queries, then store encrypted data in `eql_v2_encrypted` columns.
+### Batch Query Encryption
 
-The `@cipherstash/stack-drizzle` module provides `encryptedType` for defining encrypted columns and `createEncryptionOperators` for querying them:
+Encrypt multiple query terms in one call:
 
 ```typescript
-import { pgTable, integer, timestamp } from "drizzle-orm/pg-core"
-import { encryptedType, extractEncryptionSchema, createEncryptionOperators } from "@cipherstash/stack-drizzle"
-import { Encryption } from "@cipherstash/stack"
-
-// Define schema with encrypted columns
-const usersTable = pgTable("users", {
-  id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
-  email: encryptedType<string>("email", {
-    equality: true,
-    freeTextSearch: true,
-    orderAndRange: true,
-  }),
-  profile: encryptedType<{ name: string; bio: string }>("profile", {
-    dataType: "json",
-    searchableJson: true,
-  }),
-})
-
-// Initialize
-const usersSchema = extractEncryptionSchema(usersTable)
-const client = await Encryption({ schemas: [usersSchema] })
-const ops = createEncryptionOperators(client)
-
-// Query with auto-encrypting operators
-const results = await db.select().from(usersTable)
-  .where(await ops.eq(usersTable.email, "alice@example.com"))
+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 },
+]
 
-// JSONB queries on encrypted JSON columns
-const jsonResults = await db.select().from(usersTable)
-  .where(await ops.jsonbPathExists(usersTable.profile, "$.bio"))
+const results = await client.encryptQuery(terms)
 ```
 
-#### Drizzle `encryptedType` Config Options
-
-| Option | Type | Description |
-|---|---|---|
-| `dataType` | `"string"` \| `"number"` \| `"json"` | Plaintext data type (default: `"string"`) |
-| `equality` | `boolean` \| `TokenFilter[]` | Enable equality index |
-| `freeTextSearch` | `boolean` \| `MatchIndexOpts` | Enable free-text search index |
-| `orderAndRange` | `boolean` | Enable ORE index for sorting/range queries |
-| `searchableJson` | `boolean` | Enable JSONB path queries (requires `dataType: "json"`) |
-
-#### Drizzle JSONB Operators
+### Ordering Encrypted Data
 
-For columns with `searchableJson: true`, three JSONB operators are available:
+`ORDER BY` works on encrypted ordering columns via the domain's order term:
 
-| Operator | Description |
-|---|---|
-| `jsonbPathExists(col, selector)` | Check if a JSONB path exists (boolean, use in `WHERE`) |
-| `jsonbPathQueryFirst(col, selector)` | Extract first value at a JSONB path |
-| `jsonbGet(col, selector)` | Get value using the JSONB `->` operator |
+- **Drizzle**: `ops.asc(col)` / `ops.desc(col)` emit `ORDER BY eql_v3.ord_term(col)` (or `eql_v3.ord_term_ore` for ORE domains).
+- **Supabase**: `.order()` works on OPE-backed ordering columns — every plain `*Ord` domain plus `TextSearch`.
 
-These operators encrypt the JSON path selector using the `steVecSelector` query type and cast it to `eql_v2_encrypted` for use with the EQL PostgreSQL functions.
+The one limitation is the ORE-backed `*OrdOre` domains: their ordering term needs the superuser-only ORE operator class, which is unavailable on managed Postgres (e.g. Supabase) — the Supabase adapter rejects `order()` on those columns with a clear error. Prefer the plain `*Ord` (OPE) domains for anything you need to sort in a managed environment.
 
-### EQL v3 Concrete-Type Columns (Drizzle)
+### Drizzle Integration
 
-The `@cipherstash/stack-drizzle/v3` module targets EQL v3, where each encrypted column is a **concrete Postgres domain type** (`eql_v3.text_eq`, `eql_v3.integer_ord`, …). Instead of toggling capability flags, you pick a concrete type from the `types` namespace and its query capabilities are fixed by that choice. It is the `/v3` subpath of the same `@cipherstash/stack-drizzle` package whose v2 surface is shown above.
+The `@cipherstash/stack-drizzle/v3` subpath (of the separate `@cipherstash/stack-drizzle` package) provides Drizzle-native column factories, schema extraction, and auto-encrypting, capability-checked query operators.
 
-Declare a Drizzle table using the `types` factories. The suffix encodes the capability: `*Eq` (equality), `*Ord` (order + range, which also covers equality), `*Match` / `TextSearch` (free-text search), and the bare name (e.g. `Text`, `Bigint`) is storage-only.
+Declare a Drizzle table using the `types` factories — each factory emits its domain as the column's SQL type, so `drizzle-kit generate` produces `ADD COLUMN email public.eql_v3_text_search` etc.:
 
 ```ts
 import { pgTable, integer } from "drizzle-orm/pg-core"
@@ -385,12 +361,12 @@ const users = pgTable("users", {
   id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
   email: types.TextEq("email"),      // equality: eq / ne / inArray
   age: types.IntegerOrd("age"),      // order + range: gt/gte/lt/lte, between, asc/desc
-  bio: types.TextMatch("bio"),       // free-text search: contains
+  bio: types.TextMatch("bio"),       // free-text search: matches
   balance: types.Bigint("balance"),  // storage only (no query capability)
 })
 ```
 
-Derive the v3 schema from the table, build the typed client, and create the capability-checked operators:
+Derive the v3 schema from the table, build the typed client, and create the operators:
 
 ```ts
 const usersSchema = extractEncryptionSchemaV3(users)
@@ -419,9 +395,9 @@ const midBand = await db.select().from(users)
 const listed = await db.select().from(users)
   .where(await ops.inArray(users.email, ["alice@example.com", "bob@example.com"]))
 
-// Free-text token containment — bio is TextMatch
+// Free-text token match — bio is TextMatch
 const coffee = await db.select().from(users)
-  .where(await ops.contains(users.bio, "coffee"))
+  .where(await ops.matches(users.bio, "coffee"))
 ```
 
 Rows are **pre-encrypted** with `client.bulkEncryptModels(...)` before they reach `db.insert(...).values(...)` — Drizzle never sees plaintext. `Bigint` columns take a native JS `bigint`:
@@ -441,41 +417,99 @@ await db.insert(users).values(rows.data)
 
 Notes:
 
-- **Free-text search uses `ops.contains`** (token containment on a `match` index), not SQL `like` / `ilike`. It matches whole indexed tokens, so `contains(users.bio, "coffee")` finds rows whose `bio` contains the token `coffee`.
-- **The concrete type defines the legal operators.** `TextEq` supports `eq` / `ne` / `inArray` / `notInArray`; `*Ord` types add `gt` / `gte` / `lt` / `lte` / `between` / `notBetween` and `asc` / `desc`; `*Match` and `TextSearch` add `contains`; a bare `Text` / `Integer` / `Bigint` column is storage-only. Using an unsupported operator throws `EncryptionOperatorError`.
+- **Free-text search is `ops.matches`** (fuzzy bloom token matching on `TextMatch` / `TextSearch` columns), not SQL `like` / `ilike` — those operators do not exist on the v3 surface. `ops.contains` is a *different* operator: exact encrypted-JSON containment on `types.Json` columns.
+- **The concrete type defines the legal operators.** `TextEq` supports `eq` / `ne` / `inArray` / `notInArray`; `*Ord` types add `gt` / `gte` / `lt` / `lte` / `between` / `notBetween` and `asc` / `desc`; `TextMatch` and `TextSearch` add `matches`; `Json` supports `contains` and `selector(col, '$.path').{eq,ne,gt,gte,lt,lte}`; a bare `Text` / `Integer` / `Bigint` column is storage-only. Using an unsupported operator throws `EncryptionOperatorError`.
 - Combine conditions with `ops.and` / `ops.or`, and do NULL checks with `ops.isNull` / `ops.isNotNull` (the where-clause operators are `async` and must be `await`ed; `ops.asc` / `ops.desc` are synchronous).
 
-## Identity-Aware Encryption
+### Supabase Integration
 
-Lock encryption to a specific user by requiring a valid JWT for decryption.
+`encryptedSupabaseV3` from the separate `@cipherstash/stack-supabase` package wraps a Supabase client and **introspects the database at connect time** — it detects EQL v3 columns by their Postgres domain and builds the encryption client internally:
 
 ```typescript
-import { LockContext } from "@cipherstash/stack/identity"
+import { encryptedSupabaseV3 } from "@cipherstash/stack-supabase"
 
-// 1. Create a lock context (defaults to the "sub" claim)
-const lc = new LockContext()
+const es = await encryptedSupabaseV3(supabaseUrl, supabaseKey)
 
-// 2. Identify the user with their JWT
-const identifyResult = await lc.identify(userJwt)
+await es.from("users").insert({ email: "a@b.com", age: 30 })
+await es.from("users").select("id, email").eq("email", "a@b.com")
+await es.from("users").select("id, age").gte("age", 18).order("age")
+```
 
-if (identifyResult.failure) {
-  throw new Error(identifyResult.failure.message)
-}
+Encrypted free-text search is `matches()` (fuzzy bloom token search — `contains()` stays native, exact containment for plaintext columns), encrypted-JSON path queries are `selectorEq()` / `selectorNe()`, and `order()` works on OPE-backed ordering columns. Pass optional declared `schemas` for compile-time row types. See the `stash-supabase` skill or the [docs](https://cipherstash.com/docs) for the full guide.
+
+## Authentication
+
+The client authenticates to ZeroKMS through `config.authStrategy`. Leave it
+unset for the default **auto** strategy: in local development, authenticate
+once with `npx stash auth login` (preferred — no credentials in your
+environment); in CI/production, set the `CS_*` environment variables. Two
+explicit strategies cover the other cases:
 
-const lockContext = identifyResult.data
+- **`AccessKeyStrategy`** — service-to-service / CI. Authenticates a *service*
+  with a CipherStash access key.
+- **`OidcFederationStrategy`** — authenticates the client **as the end user**
+  by federating a third-party OIDC JWT (Clerk, Supabase, Auth0, Okta, ...)
+  into a CipherStash service token:
+
+```typescript
+import { OidcFederationStrategy } from "@cipherstash/stack"
+import { EncryptionV3 } from "@cipherstash/stack/v3"
+
+// The callback is re-invoked on every (re-)federation and must return the
+// CURRENT third-party OIDC JWT.
+const strategy = OidcFederationStrategy.create(
+  process.env.CS_WORKSPACE_CRN!,
+  () => getUserJwt(),
+)
+if (strategy.failure) throw new Error(strategy.failure.error.message)
+
+const client = await EncryptionV3({
+  schemas: [users],
+  config: { authStrategy: strategy.data },
+})
+```
+
+Authentication stands on its own — an OIDC-authenticated client encrypts and
+decrypts normally. Binding *data* to the authenticated user is a separate,
+optional step: the lock context, below.
+
+## Identity-Aware Encryption (Lock Contexts)
+
+Bind a data key to a claim from the end user's JWT, so only that user can
+decrypt. Chain `.withLockContext({ identityClaim })` on any operation:
+
+```typescript
+// Requires a client authenticated with OidcFederationStrategy (above) — the
+// claim's value resolves from the federated JWT.
+const IDENTITY = { identityClaim: ["sub"] }
 
-// 3. Encrypt with lock context
 const encrypted = await client
   .encrypt("sensitive data", { column: users.email, table: users })
-  .withLockContext(lockContext)
+  .withLockContext(IDENTITY)
+if (encrypted.failure) throw new Error(encrypted.failure.message)
 
-// 4. Decrypt with the same lock context
 const decrypted = await client
   .decrypt(encrypted.data)
-  .withLockContext(lockContext)
+  .withLockContext(IDENTITY)
 ```
 
-Lock contexts work with all operations: `encrypt`, `decrypt`, `encryptModel`, `decryptModel`, `bulkEncryptModels`, `bulkDecryptModels`, `bulkEncrypt`, `bulkDecrypt`.
+Lock contexts **require** an `OidcFederationStrategy`-authenticated client
+(the auto and access-key strategies authenticate no end user, so there is no
+JWT to resolve claims from); plain authentication never requires a lock
+context.
+
+`identityClaim` is an array of JWT claim *names* (`["sub"]`), not values, and the
+same claim must be supplied to encrypt and decrypt. Lock contexts work with all
+operations: `encrypt`, `decrypt`, `encryptModel`, `decryptModel`,
+`bulkEncryptModels`, `bulkDecryptModels`, `bulkEncrypt`, `bulkDecrypt`,
+`encryptQuery`. `.withLockContext()` also accepts a `LockContext` instance.
+On the typed client, `decryptModel` / `bulkDecryptModels` take the lock
+context as an optional third argument instead of chaining.
+
+> **Deprecated: `LockContext.identify()`.** Per-operation CTS tokens were removed
+> in `protect-ffi` 0.25; the token `identify()` fetches is no longer used by
+> encryption. Authenticate with `OidcFederationStrategy` and pass the claim
+> directly, as above.
 
 ## CLI Reference
 
@@ -502,22 +536,24 @@ npx stash init --supabase
 
 The wizard will:
 1. Authenticate with CipherStash (device code flow)
-2. Bind your device to the default Keyset
+2. Introspect your database and install the EQL v3 SQL
 3. Choose your database connection method (Drizzle ORM, Supabase JS, Prisma, or Raw SQL)
 4. Build an encryption schema interactively or use a placeholder, then generate the encryption client file
 5. Install `stash` as a dev dependency for database tooling
 
-After init, run `npx stash db setup` to configure your database.
+`init` installs EQL for you — no separate `eql install` step is needed afterward.
 
 | Flag | Description |
 |------|-------------|
-| `--supabase` | Use Supabase-specific setup flow |
+| `--supabase` / `--drizzle` / `--prisma-next` | Target a specific integration's setup flow |
+| `--proxy` / `--no-proxy` | Opt in/out of the CipherStash Proxy path |
+| `--region <slug>` | Workspace region (env `STASH_REGION`); **required for non-interactive init when not already logged in** |
 
 ## Configuration
 
 ### Local Development
 
-No environment variables or credentials are needed for local development. Run `npx @cipherstash/stack auth login` to authenticate via the device code flow, and the SDK and CLI will use the token saved to `~/.cipherstash/auth.json`.
+No environment variables or credentials are needed for local development. Run `npx stash auth login` to authenticate via the device code flow (or `npx stash init` for the agent-assisted end-to-end setup), and the SDK and CLI will use the token saved to `~/.cipherstash/auth.json`.
 
 ### Going to Production
 
@@ -537,10 +573,10 @@ See the [Going to Production](https://cipherstash.com/docs/stack/deploy/going-to
 Pass config directly when initializing the client:
 
 ```typescript
-import { Encryption } from "@cipherstash/stack"
+import { EncryptionV3 } from "@cipherstash/stack/v3"
 import { users } from "./schema"
 
-const client = await Encryption({
+const client = await EncryptionV3({
   schemas: [users],
   config: {
     workspaceCrn: "crn:ap-southeast-2.aws:your-workspace-id",
@@ -557,7 +593,7 @@ const client = await Encryption({
 Isolate encryption keys per tenant using keysets:
 
 ```typescript
-const client = await Encryption({
+const client = await EncryptionV3({
   schemas: [users],
   config: {
     keyset: { id: "123e4567-e89b-12d3-a456-426614174000" },
@@ -565,7 +601,7 @@ const client = await Encryption({
 })
 
 // or by name
-const client2 = await Encryption({
+const client2 = await EncryptionV3({
   schemas: [users],
   config: {
     keyset: { name: "Company A" },
@@ -622,73 +658,120 @@ if (result.failure) {
 
 ## API Reference
 
-### `Encryption(config)` - Initialize the client
+### `EncryptionV3(config)` - Initialize the typed client
 
 ```typescript
-function Encryption(config: EncryptionClientConfig): Promise<EncryptionClient>
+function EncryptionV3(config: {
+  schemas: AnyV3Table[]
+  config?: ClientConfig
+}): Promise<TypedEncryptionClient>
 ```
 
-### `EncryptionClient` Methods
+The wire format is pinned to EQL v3 — you don't set it yourself. `typedClient(client, ...schemas)` (same subpath) wraps an already-built `EncryptionClient` in the typed surface.
+
+### `TypedEncryptionClient` Methods
+
+Method signatures are derived from your schemas: plaintext arguments are pinned to each column's domain type, query methods only accept queryable columns, and `queryType` is constrained to the column's capabilities.
 
 | Method | Signature | Returns |
 |----|------|-----|
 | `encrypt` | `(plaintext, { column, table })` | `EncryptOperation` (thenable) |
 | `decrypt` | `(encryptedData)` | `DecryptOperation` (thenable) |
 | `encryptQuery` | `(plaintext, { column, table, queryType?, returnType? })` | `EncryptQueryOperation` (thenable) |
+
+`returnType` controls the encrypted query term's shape: `'eql'` (default, the EQL JSON payload for the ORM adapters), `'composite-literal'` (a Postgres composite string for `.eq()`/string-based APIs), or `'escaped-composite-literal'` (the same, escaped for embedding). Most users take the default; the adapters set it as needed.
 | `encryptQuery` | `(terms: ScalarQueryTerm[])` | `BatchEncryptQueryOperation` (thenable) |
-| `encryptModel` | `(model, table)` | `EncryptModelOperation<EncryptedFromSchema<T, S>>` (thenable) |
-| `decryptModel` | `(encryptedModel)` | `DecryptModelOperation<T>` (thenable) |
+| `encryptModel` | `(model, table)` | `EncryptModelOperation` (thenable) |
+| `decryptModel` | `(encryptedModel, table, lockContext?)` | `Promise<Result<...>>` |
+| `bulkEncryptModels` | `(models, table)` | `BulkEncryptModelsOperation` (thenable) |
+| `bulkDecryptModels` | `(encryptedModels, table, lockContext?)` | `Promise<Result<...>>` |
 | `bulkEncrypt` | `(plaintexts, { column, table })` | `BulkEncryptOperation` (thenable) |
 | `bulkDecrypt` | `(encryptedPayloads)` | `BulkDecryptOperation` (thenable) |
-| `bulkEncryptModels` | `(models, table)` | `BulkEncryptModelsOperation<EncryptedFromSchema<T, S>>` (thenable) |
-| `bulkDecryptModels` | `(encryptedModels)` | `BulkDecryptModelsOperation<T>` (thenable) |
+| `getEncryptConfig` | `()` | The resolved encrypt config |
+
+The thenable operations support `.withLockContext(lockContext)` for identity-aware encryption. `decryptModel` / `bulkDecryptModels` return a plain `Promise` instead — pass the lock context as the optional third argument. `decrypt` of a single value cannot be strongly typed (a lone ciphertext carries no column identity), and `encryptQuery` rejects storage-only columns at compile time.
+
+### `LockContext` (legacy)
 
-All operations are thenable (awaitable) and support `.withLockContext(lockContext)` for identity-aware encryption.
+Identity-aware encryption is done with `OidcFederationStrategy` +
+`.withLockContext({ identityClaim })` (see [Identity-Aware Encryption](#identity-aware-encryption-lock-contexts)).
+`LockContext` / `identify()` remain for backwards compatibility only — the
+per-operation CTS token `identify()` fetches was removed in `protect-ffi` 0.25
+and is no longer used by encryption.
 
-### `LockContext`
+### Schema Builders
 
 ```typescript
-import { LockContext } from "@cipherstash/stack/identity"
+import { encryptedTable, types } from "@cipherstash/stack/eql/v3"
 
-const lc = new LockContext(options?)
-const result = await lc.identify(jwtToken)
+encryptedTable(tableName, columns)  // columns: Record<string, types.*(dbColumnName)>
+types.TextSearch("email")           // one factory per public.eql_v3_* domain
 ```
 
-### Schema Builders
+Type inference helpers live on the same subpath:
 
 ```typescript
-import { encryptedTable, encryptedColumn, csValue } from "@cipherstash/stack/schema"
+import type { InferPlaintext, InferEncrypted } from "@cipherstash/stack/eql/v3"
 
-encryptedTable(tableName, columns)
-encryptedColumn(columnName)        // returns EncryptedColumn
-csValue(valueName)                 // returns ProtectValue (for nested values)
+type UserPlaintext = InferPlaintext<typeof users>
+// { email: string; age: number; balance: bigint; metadata: JsonDocument }
+
+type UserEncrypted = InferEncrypted<typeof users>
+// { email: Encrypted; age: Encrypted; ... }
 ```
 
 ## Subpath Exports
 
 | Import Path | Provides |
 |-------|-----|
-| `@cipherstash/stack` | `Encryption` function (main entry point) |
-| `@cipherstash/stack/schema` | `encryptedTable`, `encryptedColumn`, `csValue`, schema types |
+| `@cipherstash/stack/v3` | `EncryptionV3` typed client factory, `typedClient`, plus re-exports of the EQL v3 authoring DSL |
+| `@cipherstash/stack/eql/v3` | EQL v3 authoring DSL: `encryptedTable`, the `types` namespace, `buildEncryptConfig`, inference types (`InferPlaintext`, `InferEncrypted`, ...) |
+| `@cipherstash/stack` | `Encryption` function (legacy v2 entry point), auth strategies |
+| `@cipherstash/stack/schema` | Legacy v2 schema builders (see [Legacy: EQL v2](#legacy-eql-v2)) |
 | `@cipherstash/stack/identity` | `LockContext` class and identity types |
 | `@cipherstash/stack/client` | Client-safe exports (schema builders and types only - no native FFI) |
 | `@cipherstash/stack/types` | All TypeScript types (`Encrypted`, `Decrypted`, `ClientConfig`, `EncryptionClientConfig`, query types, etc.) |
-| `@cipherstash/stack/v3` | `EncryptionV3` typed client plus the EQL v3 authoring DSL (`encryptedTable`, `types`, v3 type helpers) |
 
 The Drizzle and Supabase integrations are **separate first-party packages** that
 depend on `@cipherstash/stack` (they are no longer subpaths of it):
 
 | Package | Provides |
 |-------|-----|
-| `@cipherstash/stack-drizzle` | Drizzle ORM integration (EQL v2): `encryptedType`, `extractEncryptionSchema`, `createEncryptionOperators` |
 | `@cipherstash/stack-drizzle/v3` | EQL v3 Drizzle integration: `types` column factories, `createEncryptionOperatorsV3`, `extractEncryptionSchemaV3`, `makeEqlV3Column`, `EncryptionOperatorError` |
-| `@cipherstash/stack-supabase` | Supabase integration: `encryptedSupabase` (v2) and `encryptedSupabaseV3` (v3) |
-
-## Migration from @cipherstash/protect
-
-If you are migrating from `@cipherstash/protect`, the following table maps the old API to the new one:
-
-| `@cipherstash/protect` | `@cipherstash/stack` | Import Path |
+| `@cipherstash/stack-supabase` | Supabase integration: `encryptedSupabaseV3` (and the legacy v2 `encryptedSupabase`) |
+| `@cipherstash/stack-drizzle` | Legacy EQL v2 Drizzle integration (root subpath): `encryptedType`, `extractEncryptionSchema`, `createEncryptionOperators` |
+
+## Legacy: EQL v2
+
+Before the concrete-domain types above, encrypted columns were declared with
+chainable capability builders and stored in a single `eql_v2_encrypted`
+composite column type. That surface remains fully supported for existing
+deployments, but new work should use EQL v3:
+
+- **Client and schema**: `Encryption` from `@cipherstash/stack` with
+  `encryptedColumn("email").equality().freeTextSearch().orderAndRange()` and
+  `.searchableJson()` from `@cipherstash/stack/schema`. v2 and v3 tables cannot
+  be mixed in one client.
+- **Query formatting**: v2 query terms can be rendered as strings with
+  `returnType: 'composite-literal'` / `'escaped-composite-literal'` for
+  string-based APIs.
+- **Integrations**: the v2 Drizzle surface is the root of
+  `@cipherstash/stack-drizzle` (`encryptedType`, `extractEncryptionSchema`,
+  `createEncryptionOperators`); the v2 Supabase surface is `encryptedSupabase`.
+- **DynamoDB still requires v2**: `encryptedDynamoDB` from
+  `@cipherstash/stack/dynamodb` works with the v2 API only — v3 support is
+  tracked in [#657](https://github.com/cipherstash/stack/issues/657).
+
+Full v2 documentation lives at [cipherstash.com/docs](https://cipherstash.com/docs).
+
+### Migrating from @cipherstash/protect
+
+`@cipherstash/protect` users land on the legacy v2 surface first — the mapping
+below is 1:1, and method signatures on the encryption client (`encrypt`,
+`decrypt`, `encryptModel`, etc.) and the `Result` pattern (`data` / `failure`)
+are unchanged. From there, adopt EQL v3 for new tables:
+
+| `@cipherstash/protect` | `@cipherstash/stack` (legacy v2) | Import Path |
 |------------|-----------|-------|
 | `protect(config)` | `Encryption(config)` | `@cipherstash/stack` |
 | `csTable(name, cols)` | `encryptedTable(name, cols)` | `@cipherstash/stack/schema` |
@@ -696,12 +779,11 @@ If you are migrating from `@cipherstash/protect`, the following table maps the o
 | `import { LockContext } from "@cipherstash/protect/identify"` | `import { LockContext } from "@cipherstash/stack/identity"` | `@cipherstash/stack/identity` |
 | N/A | CLI | `npx stash` |
 
-All method signatures on the encryption client (`encrypt`, `decrypt`, `encryptModel`, etc.) remain the same. The `Result` pattern (`data` / `failure`) is unchanged.
-
 ## Requirements
 
-- **Node.js** >= 18
-- The package includes a native FFI module (`@cipherstash/protect-ffi`) written in Rust and embedded via [Neon](https://github.com/neon-bindings/neon). You must opt out of bundling this package in tools like Webpack, esbuild, or Next.js (`serverExternalPackages`).
+- **Node.js** >= 22
+- The default entry includes a native FFI module (`@cipherstash/protect-ffi`). On a Node server, externalize it from bundling (e.g. Next.js `serverExternalPackages`).
+- For bundled or non-Node runtimes (Deno, Bun, Cloudflare Workers, Supabase Edge Functions), import `@cipherstash/stack/wasm-inline` instead — it inlines the WASM build, so no externalization is needed. See the [bundling guide](https://cipherstash.com/docs/stack/deploy/bundling).
 
 ## License