0 Fork 0

Files

T

Aryan Singh 473e8e01fa 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

2.7 KiB

Raw Permalink Blame History

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:

docker compose up -d    # PostgreSQL 15, Redis 7, MinIO, Keycloak (port 8180), pgAdmin (port 5050)
docker compose down

Commands

Backend (Spring Boot + Maven)

cd backend
./mvnw spring-boot:run      # Dev server on port 8081
./mvnw test                  # Run tests
./mvnw clean package         # Build JAR

Frontend (Next.js)

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)

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

2.7 KiB Raw Permalink Blame History