From 12e16c46f76dbe64f741dfee03e287bb6965bd04 Mon Sep 17 00:00:00 2001 From: Joachim Hummel Date: Thu, 21 May 2026 18:44:41 +0200 Subject: [PATCH] Add project files --- .claude/settings.json | 11 ++ CLAUDE.md | 45 +++++++ Readme.md | 1 + .../specs/2026-05-21-login-auth-design.md | 120 ++++++++++++++++++ 4 files changed, 177 insertions(+) create mode 100644 .claude/settings.json create mode 100644 CLAUDE.md create mode 100644 Readme.md create mode 100644 docs/superpowers/specs/2026-05-21-login-auth-design.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..efcf566 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,11 @@ +{ + "env": { + "ANTHROPIC_BASE_URL": "https://openrouter.ai/api", + "ANTHROPIC_AUTH_TOKEN": "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", + "ANTHROPIC_API_KEY": "", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "openai/gpt-oss-120b:free", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4-flash:free", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "openrouter/free" + } +} + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9a0af34 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,45 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview +The repository contains a web application that includes a user login feature. Details about the implementation, tech stack, and file structure are minimal in the current codebase. Future work should reference the `Readme.md` for the high‑level goal and explore the source files to understand the actual architecture. + +## Common Development Tasks +While the exact build system is not yet visible (e.g., there is no `package.json` or Makefile in the repository at this time), the typical commands for a JavaScript/Node based webapp are: + +- **Install dependencies**: `npm install` (or `yarn`/`pnpm` as appropriate) +- **Run the development server**: `npm run dev` (or the script defined in `package.json` for starting the app) +- **Run tests**: `npm test` (look for a `test` script; adjust if the project uses another test runner) +- **Run a single test**: `npm test -- ` +- **Lint the code**: `npm run lint` (or the tool specified in the project, such as `eslint` or `prettier`) +- **Build for production**: `npm run build` + +> **Note**: Verify the actual command names by inspecting the `scripts` section of `package.json` or any build configuration files present in the repository. + +## High‑Level Architecture Guidance +Because the repository does not currently expose a detailed file tree, the following steps are recommended for Claude Code to quickly become productive: + +1. **Locate the entry point** – Search for files named `index.js`, `app.js`, `server.js`, or similar. These typically bootstrap the web server or front‑end. +2. **Identify the authentication flow** – Look for modules or routes that handle login (`/login`, `auth`, `session`). Common patterns include: + - Express.js middleware (`passport`, `express-session`) + - Front‑end form handling (React, Vue, etc.) +3. **Understand data persistence** – Search for database client usage (`mongoose`, `pg`, `sequelize`, etc.) to see where user credentials are stored. +4. **Review configuration** – Check for `.env` files, `config` directories, or environment variable usage that defines secrets, database URLs, and authentication keys. +5. **Check for tests** – Look for `__tests__`, `test`, or `spec` directories; examine test files to see the expected behavior of the login feature. + +## Project‑Specific Files to Review +- `Readme.md` – Provides the high‑level goal of the project. +- Any source directories (e.g., `src/`, `server/`, `frontend/`) – Contain the implementation details. +- Configuration files (`.env.example`, `config/*.js`, `webpack.config.js`, etc.) – Define environment setup and build steps. + +## Recommendations for Future Contributors +- Keep the `README.md` up to date with exact commands for installing dependencies, running the dev server, testing, linting, and building the project. +- Add a `package.json` (or equivalent) with clearly named scripts so that Claude Code can invoke common tasks without guessing. +- Document the authentication flow (e.g., which library is used, where user sessions are stored) to accelerate onboarding. +- Include a `tests/` directory with unit/integration tests for the login functionality. + +## How Claude Code Should Use This File +- Use the **Common Development Tasks** section to infer which npm/Yarn scripts to run, but always verify the presence of those scripts in the project configuration before execution. +- Follow the **High‑Level Architecture Guidance** steps to explore the codebase efficiently when a user asks about implementation details. +- Update this `CLAUDE.md` whenever new build tools, scripts, or architectural components are added to the repository. diff --git a/Readme.md b/Readme.md new file mode 100644 index 0000000..ac50a84 --- /dev/null +++ b/Readme.md @@ -0,0 +1 @@ +Erstelle eine Webapp mit einem Benutzerlogin diff --git a/docs/superpowers/specs/2026-05-21-login-auth-design.md b/docs/superpowers/specs/2026-05-21-login-auth-design.md new file mode 100644 index 0000000..4c7d713 --- /dev/null +++ b/docs/superpowers/specs/2026-05-21-login-auth-design.md @@ -0,0 +1,120 @@ +# Login Authentication Design (Next.js, PostgreSQL, Brevo SMTP) + +## 1. Overview & Tech Stack +| Component | Technology | Reason | +|-----------|------------|--------| +| Frontend / SSR | Next.js 13 (App Router) | File‑based routing, SSR/SSG, built‑in API routes | +| Database | PostgreSQL (self‑hosted, EU datacenter) | ACID, at‑rest encryption, works with Prisma | +| ORM | Prisma 2 | Type‑safe queries, easy migrations | +| Password hashing | bcrypt (cost = 12) | Industry‑standard, slow enough to deter brute‑force | +| Tokens | JWT (HS256) | Access token ~15 min, Refresh token ~7 days | +| Session cookies | HttpOnly + Secure + SameSite=Lax (chosen by user) | XSS/CSRF protection | +| Email service | Brevo SMTP | GDPR‑compatible, simple configuration | +| Deployment | Vercel (server‑less API routes) | Automatic builds, EU region, zero‑config | +| Testing | Jest + React Testing Library, Supertest for API | Unit & integration coverage | + +## 2. Database Schema (Prisma) +```prisma +model User { + id String @id @default(cuid()) + email String @unique + passwordHash String + role Role @default(USER) + emailVerified Boolean @default(false) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + verificationTokens VerificationToken[] + passwordResetTokens PasswordResetToken[] +} + +model VerificationToken { + id String @id @default(cuid()) + token String @unique + expiresAt DateTime + userId String + user User @relation(fields: [userId], references: [id]) + createdAt DateTime @default(now()) +} + +model PasswordResetToken { + id String @id @default(cuid()) + token String @unique + expiresAt DateTime + used Boolean @default(false) + userId String + user User @relation(fields: [userId], references: [id]) + createdAt DateTime @default(now()) +} + +enum Role { + ADMIN + USER +} +``` + +## 3. API Routes (Next.js `/pages/api/...`) +| Route | Method | Purpose | Input | Output | +|------|--------|---------|-------|--------| +| `/api/auth/register` | POST | Create user, hash password, send verification mail | `{ email, password }` | 201 Created, message "Verification mail sent" | +| `/api/auth/verify-email` | GET | Validate verification token, set `emailVerified` | `?token=` | 200 OK, "Email verified" | +| `/api/auth/login` | POST | Check credentials, issue access & refresh JWT, set cookies | `{ email, password, rememberMe? }` | 200 OK, cookies set | +| `/api/auth/logout` | POST | Clear cookies, optionally blacklist refresh token | – | 200 OK | +| `/api/auth/refresh-token` | POST | Verify refresh JWT, issue new access JWT (rotate refresh if >2 days) | – (refresh cookie) | 200 OK, new cookies | +| `/api/auth/request-password-reset` | POST | Create reset token, send mail | `{ email }` | 200 OK, message "Mail sent" | +| `/api/auth/reset-password` | POST | Validate reset token, store new bcrypt hash, invalidate token | `{ token, newPassword }` | 200 OK | +| `/api/auth/me` | GET | Return current user data (no password) | – | 200 OK, `{ email, role, emailVerified }` | + +All endpoints enforce `Content-Type: application/json` and `Cache-Control: no-store`. + +## 4. Email Workflow (Brevo SMTP) +1. Registration creates a `VerificationToken` (UUID + HMAC) stored with an expiry (24 h). +2. Email template (HTML + text) contains a link: + `https://.vercel.app/api/auth/verify-email?token=<>` +3. The verification endpoint validates the token, marks the user as verified and deletes the token. +4. Password‑reset works analogously with a one‑hour token and a `used` flag. + +SMTP credentials (`BREVO_SMTP_HOST`, `BREVO_SMTP_USER`, `BREVO_SMTP_PASS`) are stored as Vercel environment variables. + +## 5. Session & Cookie Settings +| Cookie | Content | Max Age | SameSite | Secure | HttpOnly | +|--------|---------|---------|----------|--------|----------| +| `accessToken` | JWT (`sub`, `role`, `exp`) | 15 min | Lax (as requested) | true | true | +| `refreshToken` | JWT (`sub`, `exp`) | 7 days (user chose "remember me") | Lax | true | true | + +Refresh token is only set when the front‑end sends `rememberMe: true`. + +## 6. Role & Permission System +- `requireAuth` middleware validates the access token and attaches `req.user`. +- `requireRole('ADMIN')` middleware checks `req.user.role`. +- Roles are stored in the `role` column of `User` and encoded into the JWT payload. + +## 7. GDPR & Data‑Minimisation +| Measure | Implementation | +|---------|----------------| +| Minimal data | Store only email, hashed password, role, verification flag. | +| Consent | Registration form includes a mandatory "I accept the privacy policy" checkbox. | +| Right to be forgotten | `DELETE /api/users/me` removes the user row and all related tokens. | +| Data retention | Verification and reset tokens have explicit `expiresAt`; nightly Prisma job deletes expired rows. | +| Transport security | All traffic forced via HTTPS (Vercel provides TLS). | +| At‑rest encryption | PostgreSQL instance encrypted by the managed provider (EU region). | +| Audit log | Optional `AuditLog` table with pseudonymised entries, retained 30 days. | + +## 8. Deployment Pipeline (Vercel) +1. Connect the GitHub repo to Vercel. +2. Vercel runs `npm install && npm run build && npm test` on each push. +3. Preview deployments for PRs (`pr‑--.vercel.app`). +4. Production deploy on merge to `main` (`https://.vercel.app`). +5. Environment variables (`DATABASE_URL`, `NEXTAUTH_SECRET`, Brevo SMTP creds) are configured in Vercel > Settings > Environment Variables – same values for Preview and Production. + +## 9. Security Checklist +- ✅ bcrypt cost = 12 +- ✅ HttpOnly + Secure + SameSite Lax cookies +- ✅ Refresh‑token rotation on each refresh +- ✅ Rate limiting on `/login` and `/request-password-reset` +- ✅ CSP, X‑Content‑Type‑Options, Referrer‑Policy headers via `next.config.js` +- ✅ Helmet‑like security headers +- ✅ Regular dependency audit (`npm audit`) and CI fail on high severity issues + +--- +*This spec is ready for review. Once approved, the next step will be to create a detailed implementation plan.*