Import documentation: vault/CLAUDE.md
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
This commit is contained in:
arsam
+283
@@ -0,0 +1,283 @@
|
|||||||
|
# CVault — Private Code Snippet Manager
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
CVault is a private alternative to GitHub Gist. Snippets are shareable via secret links or password-protected. The app now includes a local backend with username/password accounts, Redis-backed CAPTCHA/session/rate-limit state, HTTP-only sessions, server-side snippet persistence, and server-side password/expiration checks.
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
- Next.js 16 (App Router, TypeScript, Tailwind CSS v4)
|
||||||
|
- shadcn/ui — component library (Radix + Tailwind)
|
||||||
|
- Framer Motion — animations (page transitions, stagger, layout, hover)
|
||||||
|
- @uiw/react-codemirror — code editor with syntax highlighting
|
||||||
|
- next-themes — dark/light mode toggle
|
||||||
|
- Lucide React — icons
|
||||||
|
- Geist + Geist Mono — local fonts (no CDN, served from /public/fonts/)
|
||||||
|
|
||||||
|
## Color Palette (No Purple)
|
||||||
|
- Primary: green-500 (#22c55e) / green-600 hover
|
||||||
|
- Accent: amber-500 (#f59e0b) — for password/highlights
|
||||||
|
- Background dark: zinc-950 / light: zinc-50
|
||||||
|
- Card dark: zinc-900 / light: white
|
||||||
|
|
||||||
|
## Routes
|
||||||
|
| Route | Purpose |
|
||||||
|
|---|---|
|
||||||
|
| `/` | Landing — hero, feature cards, recent snippets |
|
||||||
|
| `/login` | Username/password sign-in with local CAPTCHA |
|
||||||
|
| `/register` | Local account creation with CAPTCHA |
|
||||||
|
| `/snippets` | Library — grid/list, search, filter |
|
||||||
|
| `/snippets/new` | Create — code/text toggle, CodeMirror or textarea |
|
||||||
|
| `/snippets/[id]` | Owner view — syntax highlight, copy, share, edit, delete |
|
||||||
|
| `/snippets/[id]/edit` | Edit — pre-filled form |
|
||||||
|
| `/s/[id]` | Shared — minimal chrome, password gate |
|
||||||
|
| `/raw/[id]` | Raw plain-text output — 403 for password-protected, 404 if expired |
|
||||||
|
|
||||||
|
## Key Components
|
||||||
|
| Component | File | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| Header | `components/header.tsx` | Nav, theme toggle, mobile menu |
|
||||||
|
| Footer | `components/footer.tsx` | Coaxys credit + arsamsabbagh.ir link |
|
||||||
|
| Hero | `components/hero.tsx` | Gradient text, stagger cards |
|
||||||
|
| SnippetCard | `components/snippet-card.tsx` | Layout animation, grid/list |
|
||||||
|
| CodeEditor | `components/code-editor.tsx` | CodeMirror wrapper, 13+ langs |
|
||||||
|
| CodeViewer | `components/code-viewer.tsx` | Read-only + copy button |
|
||||||
|
| PrivacyToggle | `components/privacy-toggle.tsx` | Secret/Password slider |
|
||||||
|
| PasswordGate | `components/password-gate.tsx` | Password modal |
|
||||||
|
| SearchBar | `components/search-bar.tsx` | Live filter |
|
||||||
|
| ViewToggle | `components/view-toggle.tsx` | Grid/list switch |
|
||||||
|
| TagInput | `components/tag-input.tsx` | Comma-separated tags |
|
||||||
|
| LanguageSelector | `components/language-selector.tsx` | Language dropdown |
|
||||||
|
| ExpirationSelector | `components/expiration-selector.tsx` | Expiry dropdown |
|
||||||
|
| EmptyState | `components/empty-state.tsx` | Floating icon illustration |
|
||||||
|
| ThemeProvider | `components/theme-provider.tsx` | next-themes wrapper |
|
||||||
|
| PageTransition | `components/page-transition.tsx` | AnimatePresence wrapper |
|
||||||
|
|
||||||
|
## Animation Strategy
|
||||||
|
- All Framer Motion `initial` props set to `false` — content visible by default on SSR, animations play on client mount
|
||||||
|
- `whileHover` / `whileTap` micro-interactions on buttons/cards
|
||||||
|
- Stagger children on card grids
|
||||||
|
- Layout animations on grid/list toggle
|
||||||
|
- Hero gradient shimmer via CSS keyframes
|
||||||
|
|
||||||
|
## Data Layer
|
||||||
|
- `lib/types.ts` — Snippet interface, PrivacyType, Expiration, LANGUAGES list
|
||||||
|
- `lib/mock-data.ts` — legacy demo snippets only; production does not seed demo users/snippets
|
||||||
|
- `lib/server-db.ts` — local JSON datastore in `data/db.json`, expiration helpers, public snippet sanitizer
|
||||||
|
- `lib/server-redis.ts` — Redis client with in-memory fallback
|
||||||
|
- `lib/server-security.ts` — HTTP-only sessions and local CAPTCHA backed by Redis
|
||||||
|
- `lib/server-rate-limit.ts` — Redis-backed rate limiting
|
||||||
|
- `lib/server-password.ts` — password hashing and verification
|
||||||
|
- `lib/api-client.ts` — client-side API wrapper
|
||||||
|
- `app/api/**` — auth, snippet CRUD, and shared-snippet route handlers
|
||||||
|
- `lib/utils.ts` — cn() from shadcn
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
- Public URL: `https://snp.coaxys.ir`
|
||||||
|
- Production build: `npm run build`
|
||||||
|
- Process manager: `cvault.service` systemd unit
|
||||||
|
- App upstream: `next start -H 127.0.0.1 -p 3005`
|
||||||
|
- Nginx reverse proxy: HTTPS on port 443 → `127.0.0.1:3005`
|
||||||
|
- Redis: `REDIS_URL=redis://127.0.0.1:6379`
|
||||||
|
- Service env: `CVAULT_SECRET`, `CVAULT_SECURE_COOKIES=true`, `REDIS_URL`
|
||||||
|
- All runtime dependencies local (fonts in `/public/fonts/`, icons and editor bundled from npm, no CDN/remote ESM)
|
||||||
|
- CSP restricts scripts, styles, fonts, images, media, and API connections to local/self sources
|
||||||
|
|
||||||
|
## Production Commands
|
||||||
|
- Rebuild app: `npm run build`
|
||||||
|
- Restart app: `systemctl restart cvault.service`
|
||||||
|
- Check app: `systemctl status cvault.service --no-pager -l`
|
||||||
|
- Check nginx: `nginx -t && systemctl reload nginx`
|
||||||
|
- Check Redis: `redis-cli ping`
|
||||||
|
- Inspect Redis CVault keys: `redis-cli --scan --pattern 'cvault:*'`
|
||||||
|
|
||||||
|
## Deployment Guide
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
- Ubuntu/Debian server
|
||||||
|
- Node.js 20+ (`node --version`)
|
||||||
|
- npm 10+ (`npm --version`)
|
||||||
|
- Redis (`apt install redis-server`)
|
||||||
|
- Nginx (`apt install nginx`)
|
||||||
|
- Certbot for SSL (`apt install certbot python3-certbot-nginx`)
|
||||||
|
|
||||||
|
### 1. Transfer / Clone the Repo
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Option A — git clone (once you push to a remote)
|
||||||
|
git clone <repo-url> /srv/CVault/vault
|
||||||
|
|
||||||
|
# Option B — rsync from old server
|
||||||
|
rsync -av --exclude='.next' --exclude='node_modules' --exclude='data/' \
|
||||||
|
user@old-server:/srv/CVault/vault/ /srv/CVault/vault/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Install Dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /srv/CVault/vault
|
||||||
|
npm ci # uses package-lock.json exactly — never npm install in production
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Environment Variables
|
||||||
|
|
||||||
|
Create `/etc/cvault.env` (owned by root, mode 600):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > /etc/cvault.env << 'EOF'
|
||||||
|
CVAULT_SECRET=<generate: openssl rand -hex 32>
|
||||||
|
CVAULT_SECURE_COOKIES=true
|
||||||
|
REDIS_URL=redis://127.0.0.1:6379
|
||||||
|
NODE_ENV=production
|
||||||
|
EOF
|
||||||
|
chmod 600 /etc/cvault.env
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Build the App
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /srv/CVault/vault
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. systemd Service
|
||||||
|
|
||||||
|
Create `/etc/systemd/system/cvault.service`:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[Unit]
|
||||||
|
Description=CVault Next.js application
|
||||||
|
After=network.target redis.service
|
||||||
|
Requires=redis.service
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
User=www-data
|
||||||
|
WorkingDirectory=/srv/CVault/vault
|
||||||
|
EnvironmentFile=/etc/cvault.env
|
||||||
|
ExecStart=/usr/bin/npm start -- -H 127.0.0.1 -p 3005
|
||||||
|
Restart=on-failure
|
||||||
|
RestartSec=5
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl daemon-reload
|
||||||
|
systemctl enable cvault.service
|
||||||
|
systemctl start cvault.service
|
||||||
|
systemctl status cvault.service --no-pager -l
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Nginx + SSL
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Obtain certificate first
|
||||||
|
certbot certonly --nginx -d snp.coaxys.ir
|
||||||
|
```
|
||||||
|
|
||||||
|
Create `/etc/nginx/sites-available/cvault`:
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name snp.coaxys.ir;
|
||||||
|
return 301 https://$host$request_uri;
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl;
|
||||||
|
server_name snp.coaxys.ir;
|
||||||
|
|
||||||
|
ssl_certificate /etc/letsencrypt/live/snp.coaxys.ir/fullchain.pem;
|
||||||
|
ssl_certificate_key /etc/letsencrypt/live/snp.coaxys.ir/privkey.pem;
|
||||||
|
ssl_protocols TLSv1.2 TLSv1.3;
|
||||||
|
ssl_ciphers HIGH:!aNULL:!MD5;
|
||||||
|
|
||||||
|
client_max_body_size 2m;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
proxy_pass http://127.0.0.1:3005;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection 'upgrade';
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
proxy_cache_bypass $http_upgrade;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ln -s /etc/nginx/sites-available/cvault /etc/nginx/sites-enabled/cvault
|
||||||
|
nginx -t && systemctl reload nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. Verify
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s https://snp.coaxys.ir/api/auth/me | jq . # should return 401
|
||||||
|
redis-cli ping # PONG
|
||||||
|
systemctl status cvault.service --no-pager -l
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. File Permissions
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# App directory owned by www-data so the service can write data/db.json
|
||||||
|
chown -R www-data:www-data /srv/CVault/vault
|
||||||
|
chmod -R 755 /srv/CVault/vault
|
||||||
|
chmod 700 /srv/CVault/vault/data # restrict db access
|
||||||
|
```
|
||||||
|
|
||||||
|
### SSL Renewal (auto via systemd timer)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl status certbot.timer # should be active
|
||||||
|
# Manual renewal test:
|
||||||
|
certbot renew --dry-run
|
||||||
|
```
|
||||||
|
|
||||||
|
## What's Done
|
||||||
|
- Full frontend with all routes
|
||||||
|
- Code + Text snippet creation toggle
|
||||||
|
- CodeMirror editor with 13 language extensions
|
||||||
|
- Privacy toggle (secret link / password-protected)
|
||||||
|
- Expiration options (never, 1h, 1d, 1w)
|
||||||
|
- Tag input
|
||||||
|
- Snippet library with grid/list view + search
|
||||||
|
- View snippet with copy, share, edit, delete
|
||||||
|
- Password gate modal
|
||||||
|
- Shared snippet minimal view
|
||||||
|
- Dark/light theme (green/amber palette, zero purple)
|
||||||
|
- Footer with Coaxys + arsamsabbagh.ir link
|
||||||
|
- Responsive on mobile/tablet/desktop
|
||||||
|
- Framer Motion animations (visible-then-animate pattern)
|
||||||
|
- All fonts/resources served locally (no CDN)
|
||||||
|
- Production build + nginx proxy (HTTPS, snp.coaxys.ir)
|
||||||
|
- systemd service enabled for boot
|
||||||
|
- No demo account or demo snippets seeded in production
|
||||||
|
- `/raw/[id]` plain-text endpoint for curl/scripts
|
||||||
|
- CodeMirror theme selector — 6 themes, persisted to localStorage
|
||||||
|
- Inline share URL bar with copy button on owner view
|
||||||
|
- Live expiration countdown on cards, owner view, and shared view
|
||||||
|
- `lib/expiry-format.ts` — shared expiry formatting utility
|
||||||
|
|
||||||
|
## Backend Status
|
||||||
|
- Local username/password authentication with HTTP-only session cookie
|
||||||
|
- Fully local CAPTCHA for login and registration, stored in Redis
|
||||||
|
- Redis-backed session storage, CAPTCHA storage, and rate limits
|
||||||
|
- Server-side hashed user and snippet passwords
|
||||||
|
- Persistent server datastore in `data/db.json`
|
||||||
|
- API endpoints for snippet CRUD and shared snippet access
|
||||||
|
- Server-side password verification for shared snippets
|
||||||
|
- Server-side expiration enforcement
|
||||||
|
|
||||||
|
## What's Remaining
|
||||||
|
- PostgreSQL adapter if this needs multi-instance deployment
|
||||||
|
- Redis persistence hardening/monitoring if sessions must survive Redis restarts
|
||||||
|
- Real-time collaboration
|
||||||
|
- Comments on snippets
|
||||||
|
- Embed widgets for shared snippets
|
||||||
|
- Snippet templates
|
||||||
Reference in New Issue
Block a user