Stash Edge

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.
• A schema module shared with Node tooling fails to typecheck against the edge client.

Choosing the Entry

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.

Credentials

The edge client is passed its credentials explicitly. There is no credential discovery: ~/.cipherstash does not exist in a Worker or an Edge Function container, and there is no device-code login to fall back on.

clientId and clientKey are always required. Past those, config is a union: the access-key path below adds workspaceCrn + accessKey — the four CS_* values stash env mints — or you pass a pre-built config.authStrategy, which already carries the CRN and so needs neither workspaceCrn nor accessKey (see config.authStrategy below).

[!IMPORTANT] Server-side only — this entry never goes in a browser bundle. clientKey is a workspace secret, and it is required on every auth path, including authStrategy (OIDC federation): the core loads it as encryption key material before it ever calls the strategy, so per-user federation does not stand in for it. That is why there is no browser export condition, and there will not be one until the core changes (#804). Every runtime this entry targets is a server — Deno, a Worker, Bun — not a page.

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')!,
  },
})

Read them from the platform's environment accessor — Deno.env.get(...) on Deno/Supabase, the env binding argument on Workers, process.env on Bun.

Minting them: stash env

stash env --name my-app-prod            # print the four vars to stdout
stash env --name my-app-prod --write    # write .env.production.local (mode 0600)
stash env --name edge-dev --write .env.local

This creates a fresh ZeroKMS client and a CipherStash access key from your local stash auth login session. Things that matter here:

• The access key is shown exactly once. Pipe it straight into the secret store; it cannot be re-revealed.
• Stdout is pipe-clean — only the dotenv block goes to stdout, so stash env --name x > prod.env and pipes into secret-store CLIs are safe.
• Each run mints a new credential, and duplicate names are rejected. Use a distinct --name per environment.
• CS_CLIENT_KEY and CS_CLIENT_ACCESS_KEY are secrets. Never commit them; put placeholder names in .env.example instead.

Getting them into the runtime

# Supabase — local
supabase functions serve --env-file .env.local my-function

# Supabase — deployed
stash env --name my-app-prod --write .env.production.local
supabase secrets set --env-file .env.production.local

# Cloudflare Workers
wrangler secret put CS_CLIENT_KEY      # repeat per variable

# Vercel / other platforms
vercel env add CS_CLIENT_KEY production

Keysets and Credentials (when search returns zero rows)

An earlier version of this section described a "credential-identity rule": index terms deriving from the ZeroKMS client key, so rows written under one credential would decrypt but silently never match a query. That model is wrong. The scoping unit is the keyset, and stash-zerokms is the canonical skill for it. What actually holds:

• Search terms are produced with a per-keyset index key. Every client bound to the keyset derives the same index key, so rows written by one credential match queries from another — different CS_CLIENT_ID / CS_CLIENT_KEY pairs interoperate fully as long as both clients resolve to the same keyset.
• The routing is asymmetric (stash-zerokms has the full model): encrypt and query always use the client's bound keyset — unreachable (no grant, revoked, disabled) means client construction fails loudly at the index-key load — while decrypt follows each payload's keyset, subject to grants, with an ungranted payload failing loudly (ZeroKMS 404).
• The old cautionary scenario — stash encrypt backfill from a laptop, then querying from an Edge Function with stash env-minted values — is fine when both clients resolve to the same keyset (the common case: both created against the workspace default). If they resolve to different keysets, how it fails depends on grants: no grant across them and decrypt fails loudly too; but a reader granted the writer's keyset while bound to its own decrypts fine and silently searches the wrong keyspace — zero rows, no error. Watch the keyset-less nuance from stash-zerokms: an operation with no explicit keyset resolves to that client's default keyset, so two clients created against different keysets don't share a keyspace even in the same workspace.

If decrypt works but a query returns zero rows, it is never the credential strings. Check, in order: the reader's bound keyset against the writer's (stash-zerokms), the operand cast / predicate form (stash-postgres), and that the extractor index exists and is used (stash-indexing).

Environment hygiene still matters, for the reasons stash-auth and stash-deployment give: mint one credential set per environment with stash env, and don't point laptop profile credentials at production data.

The Client Surface

Encryption from the WASM entry. Both entries name the factory Encryption, so the import path is the only thing that distinguishes them — which makes a stray import { Encryption } from '@cipherstash/stack' easy to miss and confusing to debug, because the two clients take different config and different bulk shapes. Check the specifier first whenever an edge client behaves unexpectedly.

Every fallible method returns the same { data } | { failure } Result contract as the native client; unwrap before use.

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

const dec = await client.decrypt(enc.data)
if (dec.failure) throw new Error(dec.failure.message)

Available: encrypt, decrypt, isEncrypted, encryptQuery, encryptQueryBulk, bulkEncrypt, bulkDecrypt, encryptModel, decryptModel, bulkEncryptModels, bulkDecryptModels.

How it differs from the native typed client

Authentication and key binding are two different things, and conflating them is the standard mistake. Identity-bound encryption needs both:

1. Authenticate as the user — build an OidcFederationStrategy (or AccessKeyStrategy for service-to-service) and pass it as config.authStrategy. The client then acts, on each operation, as the user whose JWT getJwt returns (stash-auth skill, "Client lifetime"). Available on this entry, and shown below.
2. Bind the data key to a claim — chain .withLockContext({ identityClaim }) on the operation. This is what binds key retrieval to the user's claim. Not available on this entry (#797).

[!IMPORTANT] An auth strategy alone does not produce identity-bound data. It decides who the client is; a lock context decides who can retrieve a value's data key (the claim from the encrypting caller's service token is bound to the key — stash-auth is canonical). Only the first exists here, so on this entry today:

• Values you write carry no identity condition on key retrieval — any client with keyset access can decrypt them — even with a per-user authStrategy.
• You cannot read anything the native entry wrote under a lock context, because key retrieval requires the same claim. That is a silent split in what the two entries can read, on top of the schema incompatibility below.

If a value must be bound to an end-user claim, encrypt and decrypt it on the native entry. Don't reach for as any to force a lock context through here — there is nothing on the other side to receive it.

The strategy replaced the old per-operation token ceremony (LockContext.identify(), deprecated) — it did not replace the lock context, and the native entry still chains .withLockContext() for that.

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

// `create` returns a Result — unwrap it. Passing the Result itself as
// `authStrategy` is the easy mistake, and it fails opaquely later.
const strategy = OidcFederationStrategy.create(
  workspaceCrn,                   // 'crn:<region>:<workspace-id>'
  () => getUserJwt(req),          // the current request's user; runs on every operation
)
if (strategy.failure) throw new Error(strategy.failure.error.message)

const client = await Encryption({
  schemas: [users],
  config: { authStrategy: strategy.data, clientId, clientKey },
})

// Authenticated as the end user — but the value carries no identity condition
// on key retrieval. There is no `.withLockContext()` on this entry to bind it.
const enc = await client.encrypt('alice@example.com', {
  table: users,
  column: users.email,
})
if (enc.failure) throw new Error(enc.failure.message)

On the native entry, where lock contexts do exist, the same claim must be supplied on decrypt. A value encrypted under a lock context and decrypted without one — or under a different claim — does not come back. This is the single most common identity-aware encryption bug, and it does not surface as a key error; it surfaces as a failed decrypt. It is also why an edge function cannot read what a lock-context-using Node service wrote.

AccessKeyStrategy.create(workspaceCrn, accessKey) has the same Result-returning shape, for service-to-service use with a custom token store. When you pass an auth strategy, do not also pass config.accessKey — they are mutually exclusive and the client rejects the combination.

A client built with a user-scoped strategy acts as whichever user getJwt names on each operation; constructing it per request, with req captured in getJwt as above, is the simplest way to make sure that is the current one (stash-auth skill, "Client lifetime").