Add project files
This commit is contained in:
11
.claude/settings.json
Normal file
11
.claude/settings.json
Normal file
@@ -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"
|
||||
}
|
||||
}
|
||||
|
||||
45
CLAUDE.md
Normal file
45
CLAUDE.md
Normal file
@@ -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 -- <test‑file-or‑pattern>`
|
||||
- **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.
|
||||
120
docs/superpowers/specs/2026-05-21-login-auth-design.md
Normal file
120
docs/superpowers/specs/2026-05-21-login-auth-design.md
Normal file
@@ -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://<your‑app>.vercel.app/api/auth/verify-email?token=<<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‑<num>--<repo>.vercel.app`).
|
||||
4. Production deploy on merge to `main` (`https://<app>.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.*
|
||||
Reference in New Issue
Block a user