stable

Where can noy-db run?

Topology answers with proofs: device-only with no server, server-only behind an API, serverless, containers, and always-on servers.

noy-db is a TypeScript library (ESM, Node ≥22 or a modern browser — it needs the Web Crypto API and nothing else cryptographic). It runs inside your application process; there is no noy-db server. That makes the topology question really two questions per deployment: where does the code run, and where does the ciphertext live (any to-* store). The five common answers:

Topology	Persistence	Sync	Multi-user	Zero-knowledge holds?
Device-only, no server	✅ `to-browser-idb` / `to-file`	➖ none until you add a shared store	✅ on-device grants	✅ keys never leave the device
Server-only, behind your API	✅ any `to-*`	✅	✅	⚠️ toward the store, yes — but the unlocked server holds keys
Serverless	✅ cloud `to-*`	✅	✅	⚠️ same nuance; `at-*` sealing is the unlock path
Container	✅ volume or external store	✅	✅	same as its server topology
Always-on server	✅ any `to-*`	✅ (can also host the rendezvous)	✅	⚠️ same server nuance

Can it run only on my iPhone, with no server?

Yes. This is the design's home ground: offline-first, encryption on the client, no backend required. In a browser (or a web app installed on the phone — see PWA), persist with to-browser-idb; everything — encryption, queries, grants, history — happens on the device, and the only thing ever written to storage is ciphertext.

What you give up without any server: nothing functional on the device, but there is no cross-device sync until you add a shared store or transport the devices can both reach (sync, by-peer for same-network WebRTC).

Proven by: the personal notebook recipe (core-only, no services), storage showcases 01–03, and the ciphertext walk-through.

Can I use it server-only, behind my API?

Yes. The hub runs on Node ≥22 with any store — to-file on a volume, or to-postgres / to-aws-s3 / any extended store — and your API exposes whatever surface you choose (there is also in-rest, proven by showcase 47).

The honest nuance: in this topology your server opens the vault, so the server holds the keys in memory while unlocked. Zero-knowledge still holds toward the storage backend — Postgres or S3 sees only ciphertext and can't run queries — but the trust boundary is now your server process, not the end-user's device. For unattended server unlock, the at-* family (env var, OS keychain, cloud KMS) seals the secret — and it is, by design, the one non-zero-knowledge family: a host you control can decrypt the slice it unseals.

Serverless only?

Yes, with the key-handling done right.

AWS Lambda — proven end-to-end by the AWS-KMS attestation recipe (a Lambda KMS-decrypts a sealed record from S3 and renders it), with @noy-db/at-aws-kms as the sealing provider and a deployable CDK stack. Showcase 97 additionally proves the credential broker minting short-lived STS credentials against real S3 + DynamoDB.
Cloudflare Workers — the extended to-cloudflare-d1 / to-cloudflare-r2 stores target Workers backends, and the showcase suite ships a workerd vitest config (pnpm test:workers, @cloudflare/vitest-pool-workers).

Two serverless-specific notes: derive-on-unlock costs real CPU (PBKDF2 at 600,000 iterations is ~200 ms by design), so prefer at-* sealing over secret-per-invocation; and keep functions warm or scope them to flows where a cold unlock per request is acceptable.

In a container?

Yes — it's just Node. Any image with Node ≥22 runs the hub. Persistence is the only decision: a mounted volume with to-file, or (usually better for containers) an external store like to-postgres/to-aws-s3 so the container stays disposable. Unlock via at-env or your orchestrator's secret store feeding the secret.

On an always-on server?

Yes — the classic deployment, and the one you'd pick when something must be continuously reachable: hosting the broker (whose host carries four standing obligations), serving as the shared sync rendezvous store other devices push/pull through, or running scheduled passes like deferred numbering.