Add backend API for projects & snapshots

Introduce full backend API surface for projects, snapshots and user pubkeys: controllers, DTOs, JPA entities, repositories, services, and tests. Add SecurityConfig improvements (JWT decoder, audience/issuer/timestamp validation and CORS), a GlobalExceptionHandler for consistent error responses, and remove a stray test call from BackendApplication. Also update README (architecture, docs, CLI/Frontend/Backend notes), add CLAUDE.md, VSCode settings, and multiple frontend/CLI Rust changes. Small housekeeping: add .DS_Store and test adjustments.
2026-03-14 18:30:10 -05:00
1 parent 3d72c53262
commit 473e8e01fa
@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+EnvSync is a self-hosted, zero-knowledge encrypted environment variable management system — think git for `.env` files. It consists of three components:
+
+- **Backend** — Spring Boot 3 REST API (Java 21)
+- **Frontend** — Next.js 15 web dashboard (TypeScript)
+- **CLI** — Rust-based command-line tool (`cli/envsync-cli/`)
+
+## Development Infrastructure
+
+All dependent services run via Docker Compose:
+
+```bash
+docker compose up -d    # PostgreSQL 15, Redis 7, MinIO, Keycloak (port 8180), pgAdmin (port 5050)
+docker compose down
+```
+
+## Commands
+
+### Backend (Spring Boot + Maven)
+```bash
+cd backend
+./mvnw spring-boot:run      # Dev server on port 8081
+./mvnw test                  # Run tests
+./mvnw clean package         # Build JAR
+```
+
+### Frontend (Next.js)
+```bash
+cd frontend
+npm install
+npm run dev     # Dev server on port 3000
+npm run build
+npm run lint
+```
+
+Copy `frontend/.env.example` to `frontend/.env.local` and fill in Keycloak credentials before running.
+
+### CLI (Rust)
+```bash
+cd cli/envsync-cli
+cargo build             # Debug build
+cargo build --release   # Release build
+cargo test              # Run tests
+cargo clippy            # Lint
+cargo fmt               # Format
+```
+
+## Architecture
+
+### Request Flow
+```
+CLI / Browser
+    → NGINX (TLS termination)
+    → Spring Boot API (port 8081)
+        → PostgreSQL (vaults, audit logs)
+        → Redis (pub/sub for real-time notifications)
+        → MinIO (encrypted vault snapshots, S3-compatible)
+    → Keycloak (OIDC/JWT validation, port 8180)
+```
+
+### Authentication
+- **CLI** uses OAuth2 device code flow against Keycloak (`cli/envsync-cli/src/api/auth.rs`)
+- **Frontend** uses NextAuth with Keycloak OIDC provider (`frontend/src/lib/auth.ts`)
+- **Backend** is a Spring Security OAuth2 resource server — validates JWTs from Keycloak (`backend/src/main/java/.../SecurityConfig.java`)
+- Keycloak realm: `envsync`
+
+### Zero-Knowledge Encryption (CLI)
+All encryption is client-side before data reaches the server:
+- Key derivation: Argon2id
+- Encryption: XChaCha20-Poly1305 (via `sodiumoxide`/libsodium)
+- Team sharing: vault key wrapped per-member with asymmetric encryption
+- Server only stores ciphertext
+
+### CLI Commands
+Implemented in `cli/envsync-cli/src/commands/`: `init`, `push`, `pull`, `diff`, `log`, `set`, `unset`, `rollback`
+
+### Backend Config
+Key settings in `backend/src/main/resources/application.properties`:
+- PostgreSQL: `localhost:5432` (user/pass: `admin`/`admin`)
+- Redis: `localhost:6379`
+- MinIO: `http://localhost:9000` (user/pass: `minioadmin`/`minioadmin`)
+- Keycloak JWKS: `http://localhost:8180/realms/envsync`