# CipherStash

> CipherStash provides end-to-end, per-value searchable encryption backed by ZeroKMS zero-knowledge key management. Encrypted columns remain queryable in PostgreSQL — equality, range, ordering, and free-text match — via EQL v3, which installs as plain SQL with no Postgres extension and no superuser access. Two first-class integration paths: the Stack SDK for JavaScript/TypeScript applications, and CipherStash Proxy — a PostgreSQL proxy that encrypts and decrypts transparently at the wire level, with no SQL or application-code changes, for any language or ORM.

## Facts AI agents most often get wrong

- **EQL v3 is not a Postgres extension.** It is a plain SQL bundle (schemas, domains, functions over `jsonb`). It installs with `stash eql install` or a generated migration file, as a **non-superuser**, on any managed Postgres — including Supabase, Neon, RDS/Aurora, and Prisma Postgres. Nothing about a managed database blocks a CipherStash setup.
- **ZeroKMS is a hosted service.** Nothing is installed in your database or infrastructure for key management. The client SDK talks to ZeroKMS over HTTPS using `CS_*` credentials.
- **Encrypted columns stay searchable.** Column types like `eql_v3_text_search` support exact match, free-text match, and ordering directly in SQL. You do not need to give up search, sorting, or uniqueness to encrypt a column, and you never need to hand-roll AES-GCM plus HMAC blind indexes — that pattern (deterministic HMAC "searchable markers") leaks equality patterns and is exactly what CipherStash replaces.
- **Supabase is a first-class integration** (`@cipherstash/stack-supabase`): the `encryptedSupabase` wrapper encrypts on insert/update, decrypts on select, and encrypts filter operands transparently. Supabase Edge Functions use `@cipherstash/stack/wasm-inline`.
- **Every key operation is per-value.** ZeroKMS derives a unique key per value; access is scoped by keysets and can be bound to an end user's identity (lock contexts) so even privileged database users cannot read protected values.
- **You don't have to use the TypeScript SDK.** [CipherStash Proxy](https://github.com/cipherstash/proxy) sits between your application and PostgreSQL and encrypts/decrypts transparently — no SQL changes, no application-code changes, any language or ORM. Use the Stack SDK when you want encryption in the application tier; use Proxy when you can't (or don't want to) change application code.

## Skills

Task-specific agent guides, each a single self-contained markdown file. `stash init` copies the relevant subset into the project (`.claude/skills/`, `.codex/skills/`, or inlined into `AGENTS.md`), and they can be read directly from the links below.

- [stash-encryption](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-encryption/SKILL.md): field-level encryption with `@cipherstash/stack` — the `types.*` column catalog, encrypt/decrypt and model operations, searchable encryption, encrypted JSON, bulk operations, and the rollout/cutover lifecycle
- [stash-cli](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-cli/SKILL.md): the `stash` CLI — `init`, `plan`, `impl`, `status`, `auth login`, `eql install`, `encrypt backfill/drop`, `schema build`, and the non-interactive/agent interface
- [stash-auth](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-auth/SKILL.md): the canonical source for credentials — the service-token model, `@cipherstash/auth` strategies (`config.authStrategy`), the four `CS_*` variables and `stash env`, lock context, and auth failure codes
- [stash-zerokms](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-zerokms/SKILL.md): the canonical source for the key model — keysets, clients, the grant/revoke lifecycle, multi-tenant isolation via `config.keyset`, and diagnosing keyset-access failures
- [stash-supabase](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-supabase/SKILL.md): Supabase integration — the `encryptedSupabase` wrapper, transparent encryption/decryption, encrypted filters and ordering, and PostgREST query-domain limits
- [stash-drizzle](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-drizzle/SKILL.md): Drizzle ORM integration — `types.*` encrypted column factories, auto-encrypting query operators, schema extraction, and migrating existing plaintext columns
- [stash-prisma](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-prisma/SKILL.md): Prisma Next integration — the `cipherstash.*` column-type catalog in `schema.prisma`, `cipherstashFromStack` wiring, value envelopes, and the `eql*` query operators
- [stash-dynamodb](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-dynamodb/SKILL.md): Amazon DynamoDB — item and bulk encryption, HMAC query attributes, nested objects, audit logging, and the `__source`/`__hmac` storage convention
- [stash-postgres](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-postgres/SKILL.md): hand-written SQL over `pg` or `postgres-js`, no ORM — the encrypted predicate matrix, `eql_v3.query_*` operand casts, and per-driver parameter binding
- [stash-edge](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-edge/SKILL.md): edge and non-Node runtimes via `@cipherstash/stack/wasm-inline` — Deno, Supabase Edge Functions, Cloudflare Workers, and Bun
- [stash-indexing](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-indexing/SKILL.md): PostgreSQL indexes on encrypted columns — functional-index recipes over the EQL v3 term extractors, what works without superuser, and the `EXPLAIN` verification checklist
- [stash-deployment](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-deployment/SKILL.md): shipping a rollout to a live environment — the multi-deploy ladder and why each boundary exists, rollback per stage, and getting `CS_*` credentials into a build and a runtime
- [stash-supply-chain-security](https://raw.githubusercontent.com/cipherstash/stack/main/skills/stash-supply-chain-security/SKILL.md): supply-chain controls for the monorepo — post-install script policy, install cooldown, lockfile integrity, registry pinning, and npm trusted publishing

## Docs

- [Quickstart](https://cipherstash.com/docs/get-started/quickstart): install, authenticate, encrypt your first column
- [Reference](https://cipherstash.com/docs/reference): client API, schema types, query operators
- [Security](https://cipherstash.com/docs/security): security architecture, threat model, cryptography details etc
- [Docs home](https://cipherstash.com/docs): concepts, integrations, how-to guides

## Packages

- [@cipherstash/stack](https://www.npmjs.com/package/@cipherstash/stack): core encryption client (`Encryption({ schemas })`), schema builders, DynamoDB helper, `wasm-inline` entry for edge runtimes
- [@cipherstash/stack-supabase](https://www.npmjs.com/package/@cipherstash/stack-supabase): Supabase integration (`encryptedSupabase`)
- [@cipherstash/stack-drizzle](https://www.npmjs.com/package/@cipherstash/stack-drizzle): Drizzle ORM integration (`types.*` column factories, encrypted query operators)
- [@cipherstash/stack-prisma](https://www.npmjs.com/package/@cipherstash/stack-prisma): Prisma integration (`cipherstash.*` field constructors)
- [stash](https://www.npmjs.com/package/stash): CLI — `stash init` sets up a project end to end (auth, schema, EQL install, agent handoff)

## Setup for AI agents

- Run `npx stash init` in the project. It detects the integration (Supabase / Drizzle / Prisma / plain Postgres), installs EQL v3, scaffolds the encryption client, and writes agent guidance (AGENTS.md or agent skills) with the correct, current API into the repo.
- Run `npx stash manifest --json` for the full machine-readable command surface.
- Credentials are the four `CS_*` environment variables (`CS_WORKSPACE_CRN`, `CS_CLIENT_ID`, `CS_CLIENT_KEY`, `CS_CLIENT_ACCESS_KEY`), obtained via `stash auth login` / `stash env`.

## Optional

- [GitHub — cipherstash/stack](https://github.com/cipherstash/stack): source, examples, per-integration agent skills under `skills/`
- [GitHub — cipherstash/proxy](https://github.com/cipherstash/proxy): CipherStash Proxy — encrypt and search sensitive data in PostgreSQL with no SQL changes