family_wishlist/README.md

# 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 (shared 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 (shared 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`
- `DB_HOST=postgres_budget`, `DB_PORT=5432`, `DB_NAME=db_family`
- `DB_USER`, `DB_PASSWORD`, `DATABASE_URL` (sensitive values stay only in `.env`)
- `PUBLIC_APP_URL` (used for CORS in production)

### 3. Run the shared Docker stack

```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 `family-wishlist-backend`

Before first start, create a dedicated database and user for this project in the existing Postgres host:

- host: `postgres_budget`
- port: `5432`
- database: `db_family`
- user/password: set only in `.env` and do not commit them

On first start, the backend:

1. Runs `prisma db push` against the configured shared Postgres database (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://<DB_USER>:<DB_PASSWORD>@localhost:5432/db_family

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
- Dev Postgres: `localhost:5432` for local-only development data

The dev compose file stays isolated from the shared `postgres_budget` instance. Keep production credentials and local credentials in `.env`, and never hardcode them in compose files or source code.

### 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).