Architecture
A high-level map of the Keeplas codebase: a Turborepo monorepo with a Next.js app, a Convex backend, and an isolated, restricted crypto package.
Monorepo layout
Keeplas is a pnpm + Turborepo monorepo. The deployed surface is a single Next.js app; everything sensitive is isolated in its own package.
apps/web— Next.js 16 App Router app. The only deployed surface.packages/convex— Convex schema, queries, mutations, actions, and crons.packages/crypto— zero-knowledge primitives. RESTRICTED, CODEOWNER-gated.packages/ui— shared shadcn / Radix design system.
This split is deliberate. The crypto primitives are isolated so they can be audited independently, gated by CODEOWNERS, and reviewed with more rigor than feature code.
The crypto boundary
Everything in packages/crypto runs in the browser only. Convex never sees your 24-word recovery phrase, your master key, or raw Shamir shards. The server stores only:
- AES-256-GCM ciphertext (vault items, attachments, recordings)
- ML-KEM-768-wrapped keys (per-item keys, per-shard keys)
- ML-KEM-768-wrapped shards (Social Recovery)
The threat model: even a fully compromised backend cannot read user content. The provider is part of the threat model, not outside it.
The audit envelope
Every mutation that touches your vault carries a signed audit envelope. The Next.js middleware HMACs the request context (IP, country) with a shared secret (KEEPLAS_CTX_SECRET); Convex re-verifies it and appends a hash-chained, tamper-evident entry to the audit log.
This means:
- Mutations that bypass the middleware are rejected by Convex
- Tampering with a past audit entry breaks the hash chain
- You can prove, after the fact, the exact sequence of mutations that touched your vault
Authentication
Authentication is passwordless, built on Convex Auth.
- Email and WhatsApp one-time codes for sign-in
- Optional passkeys (WebAuthn) for hardware-backed credentials
- Optional TOTP for a second factor
- Per-device unlock with a PIN, biometric, or hardware key
There is no password to leak or reset. Master key derivation from the 24-word phrase happens entirely in the browser.
Stack at a glance
| Layer | Technology |
|---|---|
| Web app | Next.js 16 (App Router), React 19, Tailwind v4 |
| Backend | Convex (queries, mutations, actions, crons) |
| Auth | Convex Auth (email/WhatsApp OTP, passkeys, TOTP) |
| Crypto | AES-256-GCM, Argon2id, ML-KEM-768 (FIPS 203), Shamir Secret Sharing |
| Storage | Convex (ciphertext only) |
| Build | Turborepo, pnpm workspaces, TypeScript |
| License | AGPL-3.0 |
Further reading
- Contributing — workflow, CLA, restricted areas
- Self-Hosting — run the full stack yourself