Stash Supabase

CipherStash Stack - Supabase Integration

Guide for integrating CipherStash field-level encryption with Supabase using the encryptedSupabase wrapper over native EQL v3 column domains. The wrapper provides transparent encryption on mutations and decryption on selects, with support for equality, range, and ordering.

Naming note. encryptedSupabase is the current EQL v3 factory. encryptedSupabaseV3 remains as a @deprecated, type-identical alias, so existing imports keep working — prefer encryptedSupabase in new code. The old EQL v2 authoring wrapper (encryptedSupabase({ encryptionClient, supabaseClient }).from(table, schema)) has been removed — see "Legacy: EQL v2" at the end.

When to Use This Skill

• Adding field-level encryption to a Supabase project
• Querying encrypted data with Supabase's query builder (eq, gt, in, or, etc.)
• Understanding encrypted JSON query limitations in PostgREST
• Inserting, updating, or upserting encrypted data
• Using identity-aware encryption (lock contexts) with Supabase
• Building applications where sensitive columns need encryption at rest and in transit

On a managed AI platform — Lovable, v0, Bolt, Replit — read stash-managed-platforms first. Two things there are decided before anything on this page applies: server code runs on an edge runtime, so it needs @cipherstash/stack/wasm-inline (@cipherstash/protect is the deprecated predecessor and its native module will not load — that dead end has cost an agent a whole turn), and the database role is not postgres, which changes how EQL gets installed. encryptedSupabase can be constructed inside an edge runtime, but only from the @cipherstash/stack-supabase/wasm-inline entry and only with declared schemas — introspection is what needs a Postgres connection, and declaring your tables is what skips it. Step 5 of Setup has the call shape.

What survives PostgREST, in one line (the full treatment is under Query behaviour on encrypted columns, a long way down): eq / neq / in / match() and the range filters gt / gte / lt / lte do work on capable domains, and so does order() on OPE-backed ordering columns. Encrypted free-text matches() and encrypted-JSON contains() / selectorEq() / selectorNe() do not — they need eql_v3.query_* casts PostgREST cannot emit, and the wrapper fails fast rather than returning wrong rows. Agents guess wrong in both directions on this, so don't infer it; for the predicates that don't survive, use Drizzle, Prisma Next, or SQL in an RPC.

Installation

npm install @cipherstash/stack @cipherstash/stack-supabase @supabase/supabase-js

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.

The Supabase integration ships as its own first-party package, @cipherstash/stack-supabase, which depends on @cipherstash/stack. Install both.

Setup

Credentials first: for local development run npx stash init (the agent-assisted flow — auth, schema, and database end to end) or npx stash auth login (device code flow; no environment variables needed). CI and production use the CS_* machine-credential environment variables — see the stash-encryption skill's Configuration section. Mint them from your device session with npx stash env --name <name> (no dashboard copy-paste); this is also how Supabase Edge Functions get credentials in local dev — supabase functions serve runs in a container that cannot see ~/.cipherstash, so write the vars to a file with stash env --name edge-dev --write and pass --env-file, or supabase secrets set them for deploys.

One credential set per environment — but what must match between writers and query readers is the keyset, not the credential string. Index terms come from a per-keyset key, so any client bound to the keyset produces matching terms. Decrypt is looser — it follows each payload's keyset and needs only a grant — so a reader granted the writer's keyset but bound to a different one decrypts fine while its searches silently return zero rows. stash-zerokms is canonical for keyset scoping, stash-auth for credentials. Inside an Edge Function (Deno, no native modules) the wrapper comes from @cipherstash/stack-supabase/wasm-inline — step 5 below. For encryption without the Supabase wrapper it is @cipherstash/stack/wasm-inline, see the stash-edge skill; SQL written by hand in a migration or RPC is covered by stash-postgres.

1. Install EQL v3 on the database

Install it as a migration, not directly:

stash eql migration --supabase   # writes supabase/migrations/<timestamp>_cipherstash_eql.sql
supabase db reset                # local — replays every migration
supabase db push                 # remote/linked project

A bare supabase migration up applies to the local database. The remote forms are supabase db push and supabase migration up --linked.

⚠️ Do not use stash eql install --supabase on a project with a local supabase/ directory. It applies the SQL straight to the running database, and supabase db reset — the ordinary local development loop — drops that database and replays supabase/migrations/. EQL is not in there, so it is gone, and the next query fails with type "eql_v3_encrypted" does not exist. stash eql install --supabase is for a hosted project you administer without the Supabase CLI, where there is no migrations directory to write to.

Connecting as a role that is not postgres (or a member of it) — common on managed AI platforms such as Lovable — is fine: the install proceeds and is complete. Only the three owner-scoped ALTER DEFAULT PRIVILEGES FOR ROLE postgres statements are skipped, and they are optional: they cover EQL objects postgres might later create outside stash tooling, and every stash eql install/eql upgrade re-grants all objects anyway. The CLI prints them as "Optional SQL — requires postgres" for operators who want them (Supabase SQL editor / migration tool); on platforms where nobody can act as postgres, nothing is lost. Check ahead of time with stash eql preflight (--json for agents), which reports membership of postgres alongside the other role capabilities.

TLS: the CLI bundles the Supabase root CA, so sslmode=verify-full against Supabase hosts (direct and pooler) verifies out of the box — no certificate download, and never NODE_TLS_REJECT_UNAUTHORIZED=0 (it is process-wide and would also disable verification for CipherStash credential traffic). A supplied sslrootcert=<path> or PGSSLROOTCERT still wins.

The generated file carries three things, in order: the EQL v3 bundle, the role grants, and the cipherstash.cs_migrations tracking schema that stash encrypt records per-column progress in. One supabase db reset therefore provisions everything — no out-of-band stash eql install afterwards.

It refuses to write a second install migration; pass --force to regenerate the existing one in place (same version, so an applied ledger stays consistent). Because the version is unchanged, supabase db push will not re-apply it — the Supabase CLI decides what is pending by version, never by file content, so a version already in the ledger is never re-run and push reports Remote database is up to date. Re-apply with supabase db reset locally; on a remote, clear the ledger row first with supabase migration repair --status reverted <version> (tracking table only — it applies no SQL) and then supabase db push. Add --include-all to that push only if it aborts with Found local migration files to be inserted before the last migration on remote database., which happens when migrations sort after the install; reverting the newest version leaves it at the tail, where a plain push applies it. The flag applies every out-of-order migration you have, so don't reach for it pre-emptively. ⚠️ On a populated database, weigh it first: the EQL bundle opens with DROP SCHEMA IF EXISTS eql_v3 CASCADE (and eql_v3_internal), so re-applying also drops every index, constraint, and RLS policy that references those schemas.

If you already have encrypted-column migrations, note that the generated install is stamped with the current time and therefore sorts after them. A reset replays in version order with no dependency awareness, so those migrations run before EQL exists and supabase db reset fails with type "eql_v3_text_search" does not exist. The command detects this and warns, naming the files; the fix is to rename the install migration to a version below the earliest of them. How that back-dated version reaches a remote depends on what that remote actually has. This case only arises on a project that ran stash eql install directly, so the remote usually has EQL already — but "usually" is not what you want to bet a ledger row on, so check it:

psql "$REMOTE_DATABASE_URL" -Atc "select eql_v3.version()"

eql_v3.version() is created by the bundle's last statements, so it answers "is the whole install there". A probe for the eql_v3 schema does not: that schema is created by the bundle's first statements and survives an install that aborted partway.

If it prints a version, only the ledger row is missing — mark it applied with supabase migration repair --status applied <version>, which writes the row and runs no SQL. ⚠️ Do not push the file there instead: that re-runs the bundle's opening DROP SCHEMA IF EXISTS eql_v3 CASCADE (and eql_v3_internal), dropping every index, constraint, and RLS policy that references those schemas.

If it errors, that remote genuinely still needs the SQL applied: supabase db push --include-all, the flag being required because the back-dated version is a gap in the middle of that history. ⚠️ Never mark it applied there. Every other remedy on this page fails loudly and can be retried; this one fails silently — the ledger row claims SQL that never ran, so no later push installs EQL, and the first query against an encrypted column fails with nothing pointing at the cause.

There is no --out to reach for here: the Supabase CLI's migrations directory is not configurable. supabase db reset and supabase db push read <project>/supabase/migrations and nothing else, config.toml has no key for it, and --workdir / SUPABASE_WORKDIR moves the whole supabase/ directory rather than this subdirectory. stash eql migration --supabase --out <dir> still writes the file, and warns, because a project may have its own step that applies that directory — but the Supabase CLI will not, so EQL is gone again after the next reset.

Since eql-3.0.0 there is one v3 SQL artifact for every target — there is no separate Supabase variant. The bundle's only superuser-requiring statements (the ORE operator class/family) skip themselves when the install role lacks the privilege, and the bundle then disables the ORE-opclass-backed domains it cannot support. --supabase adds the role grants for anon / authenticated / service_role on the two schemas the bundle creates — eql_v3 (the operator-backing functions) and eql_v3_internal (SEM internals). Without the grants, encrypted queries fail loudly with a permission error (e.g. permission denied for schema eql_v3_internal).

No Exposed schemas change is needed: the column domains and their operators live in public, so bare col = term filters resolve under Supabase's default PostgREST configuration. Do not expose eql_v3_internal.

Indexing encrypted columns (no superuser needed)

Encrypted columns can and should be indexed on Supabase. Index creation needs no superuser — only the ORE opclass behind the _ord_ore domains is restricted (and those domains are disabled on non-superuser installs anyway); the default equality / ordering / match / containment indexes all install as a normal role. Do not read the ORE warning as "encrypted columns can't be indexed on Supabase."

Put the CREATE INDEX statements in a supabase/migrations/ file, one index per capability the column's domain carries:

-- eql_v3_text_eq / eql_v3_text_search: equality
CREATE INDEX users_email_eq ON users USING btree (eql_v3.eq_term(email));
-- eql_v3_<t>_ord / eql_v3_text_search: ordering + range (on numeric/date/
-- timestamp _ord domains this one index serves = too; text_ord needs the
-- eq_term index above as well)
CREATE INDEX users_created_at_ord ON users USING btree (eql_v3.ord_term(created_at));
-- eql_v3_text_match / eql_v3_text_search: free-text match
CREATE INDEX users_bio_match ON users USING gin (eql_v3.match_term(bio));
-- eql_v3_json_search: containment
CREATE INDEX users_profile_json
  ON users USING gin ((eql_v3.to_ste_vec_query(profile)::jsonb) jsonb_path_ops);

ANALYZE users;

The ANALYZE is part of the recipe — an expression index has no statistics until it runs. For the full model (which domains take which index, engagement rules, EXPLAIN verification, rollout timing), see the stash-indexing skill.

2. Database schema (per-domain columns)

Each encrypted column is declared with a concrete public.eql_v3_* domain — the domain encodes both the plaintext type and the column's query capabilities. There is no extension to enable and no generic jsonb column:

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email public.eql_v3_text_search,        -- eq + range + free-text search
  amount public.eql_v3_integer_ord,       -- eq + range
  joined_at public.eql_v3_timestamp_ord,  -- eq + range, decrypts to Date
  payload public.eql_v3_json_search,             -- encrypted JSON document
  role VARCHAR(50),                       -- regular plaintext column
  created_at TIMESTAMPTZ DEFAULT NOW()
);

The types.* member name (see declared schemas below) maps to the flat public.eql_v3_<name> domain — strip the eql_v3_ prefix and PascalCase each _-separated segment: types.TextEq → public.eql_v3_text_eq, types.IntegerOrd → public.eql_v3_integer_ord. The domains use SQL-standard type names (integer, smallint, real, double, boolean, timestamp).

3. Initialize the wrapper

import { encryptedSupabase } from "@cipherstash/stack-supabase"

// Introspects the database via options.databaseUrl or DATABASE_URL
const es = await encryptedSupabase(supabaseUrl, supabaseKey)
// or wrap an existing client: await encryptedSupabase(supabaseClient, options)

await es.from("users").insert({ email: "a@b.com", amount: 30 })
await es.from("users").select("id, email, amount").eq("email", "a@b.com")

encryptedSupabase introspects the database at connect time: it detects EQL v3 columns by their Postgres domain, derives each column's encryption config from the domain, and builds the encryption client internally — there is no client-side schema to hand-maintain. Introspection needs a direct Postgres connection (options.databaseUrl, defaulting to DATABASE_URL). The engine is a native module, so this entry runs on Node only. On an edge runtime, import the wasm-inline entry instead — step 5 below.

The native engine and pg are not the only things keeping this out of a browser. On the WASM entry, config.clientKey is a workspace secret and is required on every auth path — supplying a per-user config.authStrategy does not remove it (#804). Dropping the native engine and the pg dependency is what unblocks Deno, Supabase Edge Functions and Cloudflare Workers; nothing unblocks a browser.

Options: { schemas?, databaseUrl?, config? } — config is the encryption client config (e.g. config.authStrategy, see Authentication below).

from(tableName) takes only the table name — no schema argument. Column capabilities come from the introspected domains.

4. Optional declared schemas (compile-time types)

Declaring tables is optional. Passing schemas — a record whose keys must equal each table's name — adds compile-time types, and, when introspection also runs, verifies the declared tables against the database at construction:

import { encryptedTable, types } from "@cipherstash/stack/eql/v3"
import { encryptedSupabase } from "@cipherstash/stack-supabase"

const users = encryptedTable("users", {
  email:  types.TextSearch("email"),      // public.eql_v3_text_search — eq + range + free-text
  amount: types.IntegerOrd("amount"),     // public.eql_v3_integer_ord — eq + range
  joined: types.TimestampOrd("joined_at") // public.eql_v3_timestamp_ord — eq + range, decrypts to Date
})

const es = await encryptedSupabase(supabaseUrl, supabaseKey, {
  schemas: { users },
})

const { data } = await es.from("users").select("id, email, joined").eq("email", "a@b.com")

A declared table gets a typed builder: rows infer each column's plaintext type (types.IntegerOrd → number, types.TimestampOrd → Date), storage-only columns are excluded from every filter method, and order() is narrowed to orderable columns.

Whether undeclared tables still work turns on databaseUrl, not on the absence of schemas. Introspection is gated on a resolved database URL, so passing databaseUrl alongside schemas gets you both — declared tables keep their types and are drift-checked, undeclared ones behave exactly as with no schemas at all. Pass schemas on their own, as above, and even the native entry is in declared mode: an ambient DATABASE_URL is deliberately ignored, because declaring your tables says this client needs no connection, and from("orders") on an undeclared table throws.

Every v3 column is fully described by its types.* factory — there are no capability or tuning chains on v3 columns.

A JS property may map to a different DB column name (joined: types.TimestampOrd("joined_at")) — filters, selects, and results are translated automatically, and date/timestamp columns decrypt to real Date objects.

5. Edge runtimes — the wasm-inline entry

Deno, Supabase Edge Functions and Cloudflare Workers cannot load a native module and cannot open a raw Postgres socket. Both of those are properties of the entry above, not of the wrapper, so the package ships a second entry that has neither:

After construction the wrapper behaves the same — the filters, the transforms and the response shape are identical — with two exceptions, both of them declared mode rather than the engine. select('*') and bare select() are refused, so name the columns you want; that refusal is not a read backstop, because a query awaited with no .select() at all still returns every column undecrypted. And from() on a table you did not declare throws, because there is no introspected table list to fall back on. Both are expanded in the bullets below.

import { encryptedTable, types } from "@cipherstash/stack/eql/v3"
import { encryptedSupabase } from "@cipherstash/stack-supabase/wasm-inline"

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

const es = await encryptedSupabase(supabaseUrl, supabaseKey, {
  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")!,
  },
})

await es.from("users").select("id, email").eq("email", "a@b.com")

Either entry may author the table. encryptedTable/types from @cipherstash/stack/wasm-inline produce tables schemas accepts exactly as the @cipherstash/stack/eql/v3 ones above do — same types, same runtime. Use the wasm-inline entry when the schema module is shared with an Edge Function, so one table definition serves both sides instead of two that can drift.

If tsc rejects a wasm-inline-authored table with "Types have separate declarations of a private property 'columnName'", the installed @cipherstash/stack predates this fix — its two entries shipped separately-emitted declarations of the column class, and TypeScript compares classes with private members by declaration origin. Upgrade, or author the table from @cipherstash/stack/eql/v3 on that version. The runtime was never affected.

Four differences from the native entry, three of them enforced by the type checker:

• schemas is required — by the type, and by a construction-time throw for callers who reach it from plain JS. Nothing introspects here, so there is no other way to discover your encrypted columns, and from() on an undeclared table throws for the same reason. The real hazard is one level down: an undeclared column on a declared table never enters the encrypt config and is treated as plaintext, so a filter on it sends your plaintext value to PostgREST and a select on it hands back the raw EQL payload. Writes have a backstop — a plaintext write to a real eql_v3_* column fails that domain's CHECK constraint, though a NULL still passes. Reads have none. select('*') is refused in declared mode, but that is not a safety net: a query awaited with no .select() call at all sends a raw *, and every column comes back undecrypted, declared or not. Name the columns you want. Do not wait for a warning: the native entry logs one about unverified declarations, but it is gated on the introspector, so on this entry it never fires. Declare every encrypted column of every table you query.
• config is required. There is no ~/.cipherstash on an edge runtime to discover credentials from, so authentication is passed in. clientId and clientKey are always needed; past those the type is a union, with two supported paths. The access-key path adds workspaceCrn + accessKey — the four CS_* values shown above. Mint them with stash env --name <name> and set them with supabase secrets set, or pass --env-file for supabase functions serve. The strategy path takes a pre-built config.authStrategy instead — AccessKeyStrategy or OidcFederationStrategy, both re-exported from @cipherstash/stack/wasm-inline — and makes workspaceCrn optional, since a built strategy already carries the CRN. So authenticating as the end user over OIDC federation does work on the edge; what does not is binding data to that user, two bullets below.
• databaseUrl is not accepted. The options type declares it databaseUrl?: never, so passing one is a type error whether you write the options inline or build them as a const first, and a construction-time throw for callers arriving from plain JS.
• .withLockContext() and .audit() throw. Identity-bound encryption is not implemented on the WASM engine (cipherstash/stack#797); the entry fails loudly rather than dropping the identity claim and writing a value any keyset holder could decrypt. If you need lock contexts, that path stays on Node.

The entry is ESM-only. It is server-side, not browser-safe — the WASM client requires a workspace clientKey on every authentication path, so shipping one to a browser would ship the key with it (cipherstash/stack#804).

Insert (Encrypted Automatically)

// Single insert
const { data, error } = await es
  .from("users")
  .insert({
    email: "alice@example.com",  // encrypted automatically
    amount: 30,                  // encrypted automatically
    role: "admin",               // plaintext column, passed through
  })
  .select("id")

// Bulk insert
const { data, error } = await es
  .from("users")
  .insert([
    { email: "alice@example.com", amount: 30, role: "admin" },
    { email: "bob@example.com", amount: 25, role: "user" },
  ])
  .select("id")

Update (Encrypted Automatically)

const { data, error } = await es
  .from("users")
  .update({ email: "alice@new.example.com" })  // encrypted automatically
  .eq("id", 1)
  .select("id, email")

Upsert

const { data, error } = await es
  .from("users")
  .upsert(
    { id: 1, email: "alice@example.com", role: "admin" },
    { onConflict: "id" },
  )
  .select("id, email")

Select (Decrypted Automatically)

// All columns — select('*') (and bare select()) expands to the
// introspected column list
const { data, error } = await es.from("users").select("*")

// Explicit columns
const { data, error } = await es
  .from("users")
  .select("id, email, amount, role")
// data: [{ id: 1, email: "alice@example.com", amount: 30, role: "admin" }]

// Single result
const { data, error } = await es
  .from("users")
  .select("id, email")
  .eq("id", 1)
  .single()

// Maybe single (returns null if no match)
const { data, error } = await es
  .from("users")
  .select("id, email")
  .eq("email", "nobody@example.com")
  .maybeSingle()
// data: null

select() also accepts an optional second parameter: select(columns, { head?: boolean, count?: 'exact' | 'planned' | 'estimated' }).

Query Filters

All filter values for encrypted columns are automatically encrypted before the query executes. Filter operands are grouped by column and each column group takes one bulkEncrypt crossing — a query filtering N distinct encrypted columns makes N ZeroKMS calls, run in parallel.

Equality Filters

// Exact match (requires an equality-capable domain)
.eq("email", "alice@example.com")

// Not equal
.neq("email", "alice@example.com")

// IN array
.in("email", ["alice@example.com", "bob@example.com"])

// NULL check (no encryption needed). Use this for genuine null checks — a
// null operand passed to eq/neq is not rejected; it is forwarded unencrypted.
.is("email", null)

Free-Text Search (matches)

The current EQL 3.0.5 release requires a typed eql_v3.query_* right operand for encrypted free-text matching. PostgREST cannot express that cast, so Supabase v3 matches() fails fast. This requirement began in EQL 3.0.2 and remains in 3.0.5. Use the Drizzle or Prisma Next adapter, or expose a carefully scoped SQL/RPC path. Plaintext like/ilike queries remain native PostgREST operations.

Range/Comparison Filters

// Requires a range-capable domain (e.g. *_ord, text_search)
.gt("amount", 21)
.gte("amount", 18)
.lt("amount", 65)
.lte("amount", 100)

Match (Multi-Column Equality)

.match({ email: "alice@example.com", amount: 30 })

OR Conditions

// String format
.or("email.eq.alice@example.com,email.eq.bob@example.com")

// Structured format (more type-safe)
.or([
  { column: "email", op: "eq", value: "alice@example.com" },
  { column: "email", op: "eq", value: "bob@example.com" },
])

Both forms encrypt values for encrypted columns automatically.

NOT Filter

.not("email", "eq", "alice@example.com")

Raw Filter

.filter("email", "eq", "alice@example.com")

Delete

const { data, error } = await es
  .from("users")
  .delete()
  .eq("id", 1)

Transforms

These are passed through to Supabase directly:

.order("email", { ascending: true })  // encrypted columns: see behaviour below
.limit(10)
.range(0, 9)
.abortSignal(signal)
.throwOnError()
.returns<U>()

csv() is the exception — it throws. PostgREST serializes rows server-side, so a CSV response would carry ciphertext the wrapper never gets to decrypt. Select rows normally and serialize the decrypted data yourself:

const { data } = await es.from("users").select("id, email")
const csv = data!.map((r) => `${r.id},${r.email}`).join("\n")

order() works on plaintext columns and on OPE-backed encrypted ordering columns — see the order() bullet in the next section for exactly which domains qualify.