docs: add setup, security, and api usage guide #4
238
README.md
Normal file
238
README.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Family Wishlist
|
||||
|
||||
A small, private wishlist app for two users. Each user has their own profile, slug, and independent wishlist. Guests see a public page at `/u/<slug>` and can view active and fulfilled wishes.
|
||||
|
||||
- **Backend**: Node.js 20, Fastify 4, Prisma 5, PostgreSQL 16
|
||||
- **Frontend**: React 18, Vite 5, Tailwind CSS, TanStack Query, React Hook Form + Zod
|
||||
- **Monorepo**: pnpm workspaces
|
||||
- **Deploy**: Docker Compose (Postgres + backend + nginx-served frontend)
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- Two fixed accounts (credentials in env), password stored only as a **bcrypt hash**.
|
||||
- Wish entity: title, price, currency, link, comment, image (auto-fetched from link or uploaded).
|
||||
- Statuses: **Active → Archive / Fulfilled → Trash** (kept for 30 days, then permanently removed by a daily cron job).
|
||||
- Restore from archive or trash. Duplicate from fulfilled into a new active wish.
|
||||
- Badges on cards:
|
||||
- owner: `new` for wishes under 5 days old; `fulfilled`, `archived`, `trash` states.
|
||||
- guest: `new` if this guest hasn't seen the wish yet (tracked by a cookie-based `guestId`); fulfilled wishes look visually dimmed.
|
||||
- Archive and trash are visible **only** to the owner.
|
||||
- Profile page at `/u/:slug`, public and readable by anyone with the link.
|
||||
|
||||
---
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
apps/
|
||||
backend/ Fastify API, Prisma schema, jobs, scripts
|
||||
frontend/ React SPA
|
||||
packages/
|
||||
shared/ zod schemas + DTO types shared between backend and frontend
|
||||
docker/ Dockerfiles + nginx.conf
|
||||
docker-compose.yml prod stack (postgres + backend + frontend)
|
||||
docker-compose.dev.yml dev helper (postgres only)
|
||||
.env.example full env template
|
||||
```
|
||||
|
||||
### Backend layout (`apps/backend/src`)
|
||||
|
||||
```
|
||||
config/env.ts zod-validated process.env + resolveUsers()
|
||||
auth/users.registry.ts in-memory user registry, single source of truth for credentials
|
||||
plugins/ fastify plugins (auth, cors, cookie, jwt, rate-limit, static, guest, multipart, prisma)
|
||||
modules/
|
||||
auth/ login / logout / me
|
||||
profile/ GET / PATCH current user's profile
|
||||
wishes/ CRUD + archive/complete/restore/duplicate + soft-delete
|
||||
images/ OG-image fetcher + multipart upload + reset
|
||||
public/ public profile and wishes + guest view tracking
|
||||
meta/ /api/health + /api/version
|
||||
jobs/purge-trash.ts node-cron daily purge of wishes older than 30 days
|
||||
utils/ errors, bcrypt helpers, version helper
|
||||
```
|
||||
|
||||
### Database (Prisma)
|
||||
|
||||
See `apps/backend/prisma/schema.prisma`. Tables:
|
||||
|
||||
- `User` — `id`, `username`, `slug`, `displayName`, `bio`, `avatarUrl`. **No password hash.**
|
||||
- `Wish` — `userId`, `title`, `price`, `currency`, `url`, `comment`, `imageUrl`, `imageSource`, `status`, timestamps, `sourceWishId` (for duplicates).
|
||||
- `GuestView` — `(guestId, wishId)` pairs for "already seen" tracking.
|
||||
|
||||
### Password storage
|
||||
|
||||
The plain password is **never stored** in this application — not in the database, not in env, not in logs. Storage split:
|
||||
|
||||
| Value | Location |
|
||||
|---|---|
|
||||
| Original password | Owner's password manager only |
|
||||
| bcrypt hash | `.env` (`USER1_PASSWORD_HASH`, `USER2_PASSWORD_HASH`) |
|
||||
| Users registry | Built from env on process start, lives in RAM |
|
||||
| DB | Public fields only (username, slug, displayName) |
|
||||
| JWT | `{ id, username }` — no credentials |
|
||||
|
||||
Verification flow (see `apps/backend/src/modules/auth/auth.service.ts`):
|
||||
|
||||
1. Client `POST /api/auth/login` with `{ username, password }` over HTTPS.
|
||||
2. Server looks up user in the in-memory registry by `username`.
|
||||
3. `bcrypt.compare(password, user.passwordHash)` runs unconditionally (dummy compare if the username is unknown) — this prevents username enumeration via response timing.
|
||||
4. On success: signed JWT set as an httpOnly cookie (`fw_auth`). Rate limit: 5 logins / 10 minutes per IP.
|
||||
5. Fastify logger redacts `req.body.password`, `req.headers.cookie`, `req.headers.authorization`.
|
||||
|
||||
---
|
||||
|
||||
## Getting started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- pnpm 9+ (`corepack enable && corepack prepare pnpm@9.12.0 --activate`)
|
||||
- Docker + Docker Compose (for the full stack)
|
||||
- OpenSSL (for generating secrets)
|
||||
|
||||
### 1. Initialize git + install deps
|
||||
|
||||
```bash
|
||||
git init -b main
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### 2. Prepare the environment file
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Generate two strong secrets:
|
||||
|
||||
```bash
|
||||
openssl rand -hex 32 # paste into JWT_SECRET
|
||||
openssl rand -hex 32 # paste into COOKIE_SECRET
|
||||
```
|
||||
|
||||
Generate a bcrypt hash for each user's password (the password is only present in your shell history — clear it afterwards if you care):
|
||||
|
||||
```bash
|
||||
pnpm hash-password "Alice's strong password"
|
||||
# => $2b$12$eImiTXuWV... copy this into USER1_PASSWORD_HASH
|
||||
|
||||
pnpm hash-password "Bob's strong password"
|
||||
# => $2b$12$aBcDeFgHi... copy this into USER2_PASSWORD_HASH
|
||||
```
|
||||
|
||||
Review the rest of `.env`:
|
||||
|
||||
- `USER1_USERNAME`, `USER1_SLUG`, `USER1_DISPLAY_NAME`
|
||||
- `USER2_USERNAME`, `USER2_SLUG`, `USER2_DISPLAY_NAME`
|
||||
- `POSTGRES_*` (used by Docker)
|
||||
- `PUBLIC_APP_URL` (used for CORS in production)
|
||||
|
||||
### 3. Run everything via Docker
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
Opens:
|
||||
|
||||
- Frontend: http://localhost:8080
|
||||
- Backend API: http://localhost:8080/api (proxied by nginx) or http://localhost:3000 if you map `backend`
|
||||
- Postgres: internal only
|
||||
|
||||
On first start, the backend:
|
||||
|
||||
1. Runs `prisma db push` against the Postgres service (creates tables from `schema.prisma`; idempotent).
|
||||
2. Seeds/upserts both users from env (public fields only — password hash stays in env).
|
||||
3. Starts Fastify on port 3000.
|
||||
4. Registers the daily trash-purge cron (runs at 03:17 UTC, also once on startup).
|
||||
|
||||
> For a stricter migration workflow, switch to `prisma migrate dev` locally to produce
|
||||
> versioned migration files and change the Docker `CMD` to `prisma migrate deploy`.
|
||||
|
||||
### 4. Local development (hot reload)
|
||||
|
||||
Run Postgres in a container, apps on the host:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml up -d
|
||||
# Override DATABASE_URL to point to localhost:
|
||||
# DATABASE_URL=postgresql://wishlist:change_me@localhost:5432/family_wishlist
|
||||
|
||||
pnpm --filter @family-wishlist/backend prisma:push # apply schema (first time and on schema changes)
|
||||
pnpm --filter @family-wishlist/backend seed # upsert two users from env into DB
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
This starts both apps in parallel:
|
||||
|
||||
- Frontend: http://localhost:5173 (proxying `/api` and `/uploads` to http://localhost:3000)
|
||||
- Backend: http://localhost:3000
|
||||
|
||||
### 5. Useful scripts
|
||||
|
||||
```bash
|
||||
pnpm typecheck # typecheck all workspaces
|
||||
pnpm format # prettier on the whole repo
|
||||
pnpm hash-password "<password>" # print bcrypt hash to stdout
|
||||
pnpm --filter @family-wishlist/backend prisma:studio # GUI over DB
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
All responses are JSON. Authenticated endpoints require the `fw_auth` cookie.
|
||||
|
||||
| Method | Path | Auth | Description |
|
||||
|---|---|---|---|
|
||||
| POST | `/api/auth/login` | — | Returns auth user, sets cookie. Rate-limited. |
|
||||
| POST | `/api/auth/logout` | — | Clears cookie. |
|
||||
| GET | `/api/auth/me` | owner | Current user. |
|
||||
| GET | `/api/profile` | owner | Own profile. |
|
||||
| PATCH | `/api/profile` | owner | Update slug/displayName/bio/avatar. |
|
||||
| GET | `/api/wishes?status=active\|archived\|completed\|deleted` | owner | List own wishes. |
|
||||
| POST | `/api/wishes` | owner | Create. |
|
||||
| GET | `/api/wishes/:id` | owner | Get own wish. |
|
||||
| PATCH | `/api/wishes/:id` | owner | Update. |
|
||||
| DELETE | `/api/wishes/:id` | owner | Soft-delete (to trash). |
|
||||
| POST | `/api/wishes/:id/archive` | owner | |
|
||||
| POST | `/api/wishes/:id/complete` | owner | |
|
||||
| POST | `/api/wishes/:id/restore` | owner | From archive or trash back to active. |
|
||||
| POST | `/api/wishes/:id/duplicate` | owner | Copy fulfilled wish into a new active one. |
|
||||
| POST | `/api/wishes/:id/image` | owner | Multipart image upload. |
|
||||
| POST | `/api/wishes/:id/image/refresh-og` | owner | Re-fetch OG image from link. |
|
||||
| DELETE | `/api/wishes/:id/image` | owner | Reset to default. |
|
||||
| GET | `/api/public/:slug` | — | Public profile. |
|
||||
| GET | `/api/public/:slug/wishes` | — | Active + fulfilled wishes. Sets `isNewForGuest`. |
|
||||
| POST | `/api/public/:slug/views` | — | Body `{ wishIds: [] }`. Marks as seen. |
|
||||
| GET | `/api/health`, `/api/version` | — | Meta. |
|
||||
|
||||
---
|
||||
|
||||
## Versioning
|
||||
|
||||
Each package has its own version (`apps/backend/package.json` and `apps/frontend/package.json`). The app footer shows both:
|
||||
|
||||
```
|
||||
frontend v0.1.0 · backend v0.1.0
|
||||
```
|
||||
|
||||
Bump them per semver on each change:
|
||||
- patch — bug fixes and small non-breaking tweaks,
|
||||
- minor — backward-compatible features,
|
||||
- major — breaking changes.
|
||||
|
||||
---
|
||||
|
||||
## Security notes
|
||||
|
||||
- Cookies are `httpOnly`, `SameSite=Lax`, `Secure` in production.
|
||||
- All auth-scoped routes re-check ownership in the service layer (`userId` vs `req.user.id`).
|
||||
- `/api/auth/login` is rate-limited; username enumeration is mitigated by a constant-time dummy compare.
|
||||
- Image fetcher has a 10s timeout, a 5 MB cap, and accepts only `image/jpeg|png|webp|gif`.
|
||||
- Multipart upload cap: 8 MB, one file per request.
|
||||
- Prisma cascades delete `GuestView` rows when their wish is purged.
|
||||
- In production, terminate TLS in front of the nginx container (Caddy / Traefik / cloud load balancer).
|
||||
Reference in New Issue
Block a user