From 8af01e8310084df36999fd62b7c7eb16aa19af52 Mon Sep 17 00:00:00 2001
From: jslyonnais <6282845+jslyonnais@users.noreply.github.com>
Date: Fri, 20 Feb 2026 13:13:47 -0500
Subject: [PATCH 1/2] readme + env
---
.env.example | 5 +-
README.md | 298 +++++++--------------------
src/env.ts | 3 +-
src/integrations/clerk/provider.tsx | 3 +-
src/integrations/convex/provider.tsx | 3 +-
5 files changed, 85 insertions(+), 227 deletions(-)
diff --git a/.env.example b/.env.example
index 50a8c82..1b6a5f6 100644
--- a/.env.example
+++ b/.env.example
@@ -1,4 +1,3 @@
-# team: devjs, project: forms
CONVEX_DEPLOYMENT=
# Clerk configuration, get this key from your [Dashboard](dashboard.clerk.com)
@@ -6,6 +5,4 @@ VITE_CLERK_PUBLISHABLE_KEY=
CLERK_JWT_ISSUER_DOMAIN=
VITE_CONVEX_URL=
-VITE_CONVEX_SITE_URL=
-
-VITE_LOG_LEVEL=debug
\ No newline at end of file
+VITE_CONVEX_SITE_URL=
\ No newline at end of file
diff --git a/README.md b/README.md
index ed87589..fee3812 100644
--- a/README.md
+++ b/README.md
@@ -1,240 +1,98 @@
-Welcome to your new TanStack Start app!
-
-# Getting Started
-
-To run this application:
-
-```bash
-npm install
-npm run dev
-```
-
-# Building For Production
-
-To build this application for production:
-
-```bash
-npm run build
-```
-
-## Testing
-
-This project uses [Vitest](https://vitest.dev/) for testing. You can run the tests with:
-
-```bash
-npm run test
-```
-
-## Styling
-
-This project uses [Tailwind CSS](https://tailwindcss.com/) for styling.
-
-### Removing Tailwind CSS
-
-If you prefer not to use Tailwind CSS:
-
-1. Remove the demo pages in `src/routes/demo/`
-2. Replace the Tailwind import in `src/styles.css` with your own styles
-3. Remove `tailwindcss()` from the plugins array in `vite.config.ts`
-4. Uninstall the packages: `npm install @tailwindcss/vite tailwindcss -D`
-
-## Linting & Formatting
-
-This project uses [eslint](https://eslint.org/) and [prettier](https://prettier.io/) for linting and formatting. Eslint is configured using [tanstack/eslint-config](https://tanstack.com/config/latest/docs/eslint). The following scripts are available:
-
-```bash
-npm run lint
-npm run format
-npm run check
+# Tanstack Start - With E2E Encryption Demo
+
+A TanStack Start starter with Convex, Clerk, and end-to-end encryption.
+
+Full-stack React starter with zero-knowledge architecture. Sensitive data is encrypted client-side before it reaches the server; the backend never has access to decryption keys or plaintext.
+
+## Tech Stack
+
+- **Frontend:** TanStack Start, TanStack Router, TanStack Query
+- **Backend:** Convex (real-time database)
+- **Auth:** Clerk
+- **Encryption:** OpenPGP.js (ECC P-256), @scure/bip39 (passphrase generation)
+- **UI:** Tailwind CSS, shadcn, Radix UI
+- **State:** Jotai
+
+## Zero-Knowledge Architecture
+
+```mermaid
+flowchart TD
+ subgraph client [Client]
+ SignUp[Sign Up]
+ GenKeys[Generate PGP Key Pair]
+ EncPass[Encrypt Passphrase with Password]
+ StoreKeys[Store to Convex]
+ SignUp --> GenKeys --> EncPass --> StoreKeys
+ end
+
+ subgraph convex [Convex]
+ UserKeys[(userKeys table)]
+ StoreKeys -->|encryptedPrivateKey, publicKey, encryptedPassphrase| UserKeys
+ end
+
+ subgraph zk [Zero Knowledge]
+ NoPlaintext[Convex never sees plaintext]
+ NoPrivateKey[Private key never leaves client]
+ end
```
-## Setting up Clerk
-
-- Set the `VITE_CLERK_PUBLISHABLE_KEY` in your `.env.local`.
-
-## Setting up Convex
-
-- Set the `VITE_CONVEX_URL` and `CONVEX_DEPLOYMENT` environment variables in your `.env.local`. (Or run `npx -y convex init` to set them automatically.)
-- Run `npx -y convex dev` to start the Convex server.
+- **Key generation:** PGP key pairs (ECC nistP256) generated client-side in `src/lib/crypto.ts` during signup
+- **Passphrase:** 12-word BIP39 mnemonic (128-bit entropy), encrypted with the user's Clerk password before storage
+- **Storage:** Convex stores only encrypted blobs—`encryptedPrivateKey`, `publicKey`, `encryptedPassphrase`
+- **Usage:** `useEncryption` hook (`src/hooks/useEncryption.ts`) encrypts/decrypts data client-side; Convex cannot decrypt
-# Paraglide i18n
+## Prerequisites
-This add-on wires up ParaglideJS for localized routing and message formatting.
+- Node.js 18+
+- [Clerk](https://clerk.com) account
+- [Convex](https://convex.dev) account
-- Messages live in `project.inlang/messages`.
-- URLs are localized through the Paraglide Vite plugin and router `rewrite` hooks.
-- Run the dev server or build to regenerate the `src/paraglide` outputs.
-
-## Shadcn
-
-Add components using the latest version of [Shadcn](https://ui.shadcn.com/).
+## Getting Started
```bash
-pnpm dlx shadcn@latest add button
-```
-
-## T3Env
-
-- You can use T3Env to add type safety to your environment variables.
-- Add Environment variables to the `src/env.mjs` file.
-- Use the environment variables in your code.
-
-### Usage
-
-```ts
-import { env } from '@/env'
-
-console.log(env.VITE_APP_TITLE)
-```
-
-## Routing
-
-This project uses [TanStack Router](https://tanstack.com/router) with file-based routing. Routes are managed as files in `src/routes`.
-
-### Adding A Route
-
-To add a new route to your application just add a new file in the `./src/routes` directory.
-
-TanStack will automatically generate the content of the route file for you.
-
-Now that you have two routes you can use a `Link` component to navigate between them.
-
-### Adding Links
-
-To use SPA (Single Page Application) navigation you will need to import the `Link` component from `@tanstack/react-router`.
-
-```tsx
-import { Link } from '@tanstack/react-router'
+npm install # Install dependencies packages
+cp .env.example .env.local # Edit .env.local with your keys
+npm run start # Starts Convex dev + Vite (port 3666)
```
-Then anywhere in your JSX you can use it like so:
+**Required environment variables** (from `.env.example`):
-```tsx
-About
-```
-
-This will create a link that will navigate to the `/about` route.
-
-More information on the `Link` component can be found in the [Link documentation](https://tanstack.com/router/v1/docs/framework/react/api/router/linkComponent).
-
-### Using A Layout
-
-In the File Based Routing setup the layout is located in `src/routes/__root.tsx`. Anything you add to the root route will appear in all the routes. The route content will appear in the JSX where you render `{children}` in the `shellComponent`.
-
-Here is an example layout that includes a header:
-
-```tsx
-import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
-
-export const Route = createRootRoute({
- head: () => ({
- meta: [
- { charSet: 'utf-8' },
- { name: 'viewport', content: 'width=device-width, initial-scale=1' },
- { title: 'My App' },
- ],
- }),
- shellComponent: ({ children }) => (
-
-
-
-
-
-
-
-
- {children}
-
-
-
- ),
-})
-```
-
-More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
+| Variable | Description |
+| -------------------------------------- | ------------------------------------- |
+| `VITE_CLERK_PUBLISHABLE_KEY` | From Clerk Dashboard |
+| `CLERK_JWT_ISSUER_DOMAIN` | For Convex JWT verification |
+| `VITE_CONVEX_URL`, `CONVEX_DEPLOYMENT` | Run `npx convex init` or set manually |
-## Server Functions
+## Scripts
-TanStack Start provides server functions that allow you to write server-side code that seamlessly integrates with your client components.
+| Script | Description |
+| ---------------- | ---------------------------- |
+| `npm run start` | Convex dev + Vite dev server |
+| `npm run dev` | Vite only (port 3666) |
+| `npm run build` | Production build |
+| `npm run test` | Vitest |
+| `npm run lint` | ESLint |
+| `npm run format` | Prettier |
-```tsx
-import { createServerFn } from '@tanstack/react-start'
+## Project Structure
-const getServerTime = createServerFn({
- method: 'GET',
-}).handler(async () => {
- return new Date().toISOString()
-})
-
-// Use in a component
-function MyComponent() {
- const [time, setTime] = useState('')
-
- useEffect(() => {
- getServerTime().then(setTime)
- }, [])
-
- return
Server time: {time}
-}
-```
-
-## API Routes
-
-You can create API routes by using the `server` property in your route definitions:
-
-```tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { json } from '@tanstack/react-start'
-
-export const Route = createFileRoute('/api/hello')({
- server: {
- handlers: {
- GET: () => json({ message: 'Hello, World!' }),
- },
- },
-})
-```
-
-## Data Fetching
-
-There are multiple ways to fetch data in your application. You can use TanStack Query to fetch data from a server. But you can also use the `loader` functionality built into TanStack Router to load the data for a route before it's rendered.
-
-For example:
-
-```tsx
-import { createFileRoute } from '@tanstack/react-router'
-
-export const Route = createFileRoute('/people')({
- loader: async () => {
- const response = await fetch('https://swapi.dev/api/people')
- return response.json()
- },
- component: PeopleComponent,
-})
-
-function PeopleComponent() {
- const data = Route.useLoaderData()
- return (
-