/stash-edge

name: stash-edge
description: Run CipherStash encryption on edge and non-Node runtimes with the `@cipherstash/stack/wasm-inline` entry — Deno, Supabase Edge Functions, Cloudflare Workers, and Bun. Covers the import specifier per runtime, which `CS_*` variables are mandatory and minting them with `stash env`, how keysets and credentials interact on the edge (what must match is the keyset — `stash-zerokms` is canonical), how the WASM client surface differs from the native typed client, why the entry is server-side only and never belongs in a browser bundle, and how one EQL v3 schema module is shared across both entries. Use when adding encryption to a Supabase Edge Function, a Worker, or a Deno service; when a native module fails to load in a deployed runtime; when wiring `CS_*` secrets into an edge deploy; or when encrypted search returns zero rows on the edge but works locally.

Encryption on the Edge (WASM entry)

`@cipherstash/stack` has two runtime entries. The default one binds a Node-API native module and must be loaded by Node's own `require`. **`@cipherstash/stack/wasm-inline` is the entry for everywhere else** — it carries the WASM build of the same engine as a base64 blob inside the JS, so there is no native binding, no separate `.wasm` fetch, and nothing for a bundler to externalise.

This skill covers that entry and the deployment shape around it. It is EQL v3 throughout. For the SQL that actually queries the encrypted columns — the predicate forms and driver binding rules — see `stash-postgres`; edge functions almost always talk to Postgres over a raw driver, so the two are usually read together.

When to Use This Skill

• Adding encryption to a Supabase Edge Function, Cloudflare Worker, Deno

service, or Bun app.

• A deployed runtime fails to load the native module (`protect-ffi`), or a

bundler chokes trying to include it.

• Wiring `CS_*` credentials into an edge deploy, or minting them at all.
• Encrypted search works locally but returns **zero rows** in the deployed

function — see [Keysets and Credentials](#keysets-and-credentials-when-search-returns-zero-rows).

• A schema module shared with Node tooling fails to typecheck against the

edge client.

Choosing the Entry

| Runtime | Entry | Why | |---|---|---| | Node server, Next.js server code | `@cipherstash/stack` (+ `/v3`) | Native NAPI is faster; the native module must be excluded from bundling — see the [bundling guide](https://cipherstash.com/docs/stack/deploy/bundling) | | Supabase Edge Functions | `@cipherstash/stack/wasm-inline` | Deno, V8-only, no native modules | | Cloudflare Workers | `@cipherstash/stack/wasm-inline` | V8 isolate, no native modules | | Deno (any) | `@cipherstash/stack/wasm-inline` | No NAPI under Deno's default permissions | | Bun | `@cipherstash/stack/wasm-inline` | Works, and avoids native-module resolution differences | | Anywhere bundling server code | `@cipherstash/stack/wasm-inline` | Bundles cleanly; nothing to externalise |

**The Supabase adapter has its own edge entry.** If you are using `@cipherstash/stack-supabase`, import `@cipherstash/stack-supabase/wasm-inline` (not the package root, which pulls the native engine) and **declare your `schemas`** — the adapter's default behaviour is to introspect the database for its column config, which needs a Postgres connection. Declaring skips it. Those `schemas` can be authored from either `@cipherstash/stack/eql/v3` or `@cipherstash/stack/wasm-inline` — both entries resolve one declaration of the column classes, so the tables are interchangeable. See "Schema Modules Cross Entries" below, plus `stash-supabase` and `stash-managed-platforms`.

**`@cipherstash/protect` is not one of the options.** It is the deprecated predecessor of `@cipherstash/stack`; its native `@cipherstash/protect-ffi` dependency will not load in any of the runtimes above. Reasoning from *that* package's dependency tree to "CipherStash cannot run on the edge" is a wrong conclusion drawn from the wrong package — it has already cost one agent a full turn on a hosted platform. The row you want is `wasm-inline`. (On a managed AI platform specifically — Lovable, v0, Bolt, Replit — see `stash-managed-platforms`.)

**The WASM entry is ESM-only.** Its `exports` map has an `import` condition and no `require` — deliberately, since the runtimes it targets are ESM. A CJS `require('@cipherstash/stack/wasm-inline')` will not resolve. Node consumers that need it must be ESM (`"type": "module"` or `.mjs`).

Importing It

Supabase Edge Functions / Deno — `npm:` specifier

The Edge runtime resolves `npm:` specifiers at function start; there is no build step.

import {
  Encryption, encryptedTable, types, isEncrypted,
} from 'npm:@cipherstash/stack@1.2.1/wasm-inline'

**Pin an exact version.** Deno caches by specifier, so an unpinned import drifts between deploys — pin, and bump the pin deliberately. Check what is current with `npm view @cipherstash/stack dist-tags`.

Deno with an import map

For a project with a `deno.json`, map the specifier once and import the bare name everywhere:

{
  "imports": {
    "@cipherstash/stack/wasm-inline": "npm:@cipherstash/stack@1.2.1/wasm-inline"
  }
}

import { Encryption, encryptedTable, types } from '@cipherstash/stack/wasm-inline'

> **No `--allow-ffi` needed.** The whole point of this entry is that nothing > native loads. If a Deno process running this entry ever demands an FFI > permission, something has resolved the native entry instead — check the > import path before granting anything.

Cloudflare Workers / Bun / bundlers — normal install

npm install @cipherstash/stack

import { Encryption, encryptedTable, types } from '@cipherstash/stack/wasm-inline'

No `externals`, no `nodeExternals`, no `serverExternalPackages` entry. If a build config already externalises the native module for the default entry, that config does not apply here and can be left alone.

#