From 41a997a381d3067a8bd10c32733701c1d902829d Mon Sep 17 00:00:00 2001 From: Toby Hede Date: Wed, 26 Aug 2026 18:27:50 +1000 Subject: [PATCH] docs(reference): the Supabase SDK has two entry points, and the edge one runs in a Worker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/reference/supabase-sdk.md` still described the state before #912: one entry point, and a factory that "cannot run in a Worker or the browser". #912 added `@cipherstash/stack-supabase/wasm-inline`, which carries no Postgres driver and takes declared `schemas` instead of introspecting. Introspection was the only thing that needed a Postgres socket, so that entry does run in a Worker. The reference never said so. Corrects both halves: - the "One entry point" table now lists both, with the engine, how each learns the schema, and where each runs; - the factory paragraph now scopes its restriction to the native entry and points at the edge entry as the way to run in a Worker. The browser half of the old sentence was correct and is kept, with the reason named: the WASM client requires a workspace `clientKey` on every auth path (cipherstash/stack#804). Internal reference documentation — no package ships `docs/`, so no changeset. The same stale sentence is still live in `skills/stash-supabase/SKILL.md` and `packages/stack-supabase/README.md`, both of which DO ship; those are tracked separately. Claude-Session: https://claude.ai/code/session_01E1J2nVGJWVkqvLepDfinRf --- docs/reference/supabase-sdk.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/reference/supabase-sdk.md b/docs/reference/supabase-sdk.md index abbfa66d4..c2a8806f3 100644 --- a/docs/reference/supabase-sdk.md +++ b/docs/reference/supabase-sdk.md @@ -4,11 +4,16 @@ are transparently encrypted on mutations, `::jsonb`-cast on selects, encrypted in filter terms, and decrypted in results. -One entry point, EQL v3 only: +Two entry points, EQL v3 only: -| Entry point | Schema DSL | Column storage | -|---|---|---| -| `encryptedSupabase` | `@cipherstash/stack/eql/v3` (EQL v3) | native `public.eql_v3_*` domains | +| Entry point | Engine | Schema | Runtime | +|---|---|---|---| +| `@cipherstash/stack-supabase` | native | introspected from `public.eql_v3_*` domains | Node | +| `@cipherstash/stack-supabase/wasm-inline` | WASM | declared — `schemas` is required | edge (Deno, Supabase Edge Functions, Cloudflare Workers) | + +Both author columns with `@cipherstash/stack/eql/v3` and store them in native +`public.eql_v3_*` domains. They differ only in how the wrapper learns the +schema, and therefore in where it can run. Rows already written as EQL v2 still decrypt through `@cipherstash/stack`; what is gone is the ability to author new v2 columns here. @@ -30,8 +35,14 @@ free-text by bloom-filter containment). 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. Introspection needs a direct Postgres connection -(`options.databaseUrl`, defaulting to `DATABASE_URL`), so the factory cannot -run in a Worker or the browser. +(`options.databaseUrl`, defaulting to `DATABASE_URL`), so this entry cannot run +in a Worker. + +Introspection is the only thing that needs Postgres. To run in a Worker, import +`@cipherstash/stack-supabase/wasm-inline` and declare your tables in `schemas` +instead — that entry carries no Postgres driver and never introspects. It is +still server-side: it is not browser-safe, because the WASM client requires a +workspace `clientKey` on every auth path (cipherstash/stack#804). ```typescript import { encryptedSupabase } from '@cipherstash/stack-supabase'