Aryan Singh
473e8e01fa
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.
88 lines
2.7 KiB
Markdown
88 lines
2.7 KiB
Markdown
# 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`
|