securepool 1.0.0

package/DEPLOYMENT.md

@@ -0,0 +1,441 @@
+# SecurePool - Deployment Guide
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
+│  Frontend        │────▶│  Backend API      │────▶│  MongoDB     │
+│  (Vercel)        │     │  (Railway/Render) │     │  (Atlas)     │
+│  Static files    │     │  Node.js server   │     │  Cloud DB    │
+└─────────────────┘     └──────────────────┘     └─────────────┘
+  apps/demo-frontend      apps/demo-backend        MongoDB Atlas
+```
+
+### Deployment Targets
+
+| What | Platform | Why |
+|------|----------|-----|
+| Database | MongoDB Atlas | Free cloud DB, no server to manage |
+| Backend API | Railway / Render | Node.js hosting, auto-deploys from GitHub |
+| Frontend | Vercel / Netlify | Free static hosting, auto-deploys from GitHub |
+| NPM Packages | npmjs.com | So other devs can install your library |
+
+---
+
+## Prerequisites
+
+Before deploying, make sure:
+
+- [ ] Your code is pushed to a **GitHub repository**
+- [ ] You have accounts on [MongoDB Atlas](https://cloud.mongodb.com), [Railway](https://railway.app), and [Vercel](https://vercel.com)
+- [ ] Your project builds locally (`npm run build` succeeds)
+- [ ] Your `.pem` files are ready (you'll convert them to env vars)
+
+---
+
+## Step 1: MongoDB Atlas (Cloud Database)
+
+### 1.1 Create Cluster
+
+1. Go to https://cloud.mongodb.com
+2. Click **"Build a Database"**
+3. Choose **M0 Free Tier**
+4. Select region closest to your backend (e.g., AWS Mumbai for India)
+5. Click **Create**
+
+### 1.2 Create Database User
+
+1. Go to **Database Access** (left sidebar)
+2. Click **"Add New Database User"**
+3. Set:
+   - Username: `securepool-user`
+   - Password: `SecurePool@123`
+   - Role: **Read and write to any database**
+4. Click **Add User**
+
+### 1.3 Allow Network Access
+
+1. Go to **Network Access** (left sidebar)
+2. Click **"Add IP Address"**
+3. Click **"Allow Access from Anywhere"** (`0.0.0.0/0`)
+4. Click **Confirm**
+
+> For production, restrict to your backend server's IP only.
+
+### 1.4 Get Connection String
+
+1. Go to **Database** (left sidebar)
+2. Click **"Connect"** on your cluster
+3. Choose **"Drivers"**
+4. Copy the connection string:
+
+```
+mongodb+srv://securepool-user:SecurePool%40123@cluster0.xxxxx.mongodb.net/securepool
+```
+
+> Replace `cluster0.xxxxx` with your actual cluster address.
+> The `@` in password is encoded as `%40`.
+
+### 1.5 Verify Connection
+
+Test from your terminal:
+
+```bash
+mongosh "mongodb+srv://securepool-user:SecurePool%40123@cluster0.xxxxx.mongodb.net/securepool"
+```
+
+If it connects, your database is ready.
+
+---
+
+## Step 2: Prepare JWT Keys for Production
+
+Locally, you use `.pem` files. In production, you pass the key content as environment variables.
+
+### Convert .pem files to single-line format
+
+Run these in your `securepool/` directory:
+
+```bash
+# Private key (copy the entire output)
+awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' private.pem
+```
+
+```bash
+# Public key (copy the entire output)
+awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' public.pem
+```
+
+Each command outputs a single line like:
+
+```
+-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n
+```
+
+**Save both outputs** — you'll paste them as env vars in Railway.
+
+---
+
+## Step 3: Deploy Backend on Railway
+
+### 3.1 Create Project
+
+1. Go to https://railway.app
+2. Click **"New Project"**
+3. Choose **"Deploy from GitHub Repo"**
+4. Select your repository
+5. Railway auto-detects Node.js
+
+### 3.2 Configure Build & Start
+
+Go to your service → **Settings** tab:
+
+| Setting | Value |
+|---------|-------|
+| Root Directory | `/` (leave empty, monorepo root) |
+| Build Command | `npm ci && npx turbo run build --filter=@securepool/* && cd apps/demo-backend && npx tsc` |
+| Start Command | `node apps/demo-backend/dist/index.js` |
+
+### 3.3 Add Environment Variables
+
+Go to **Variables** tab and add each:
+
+```env
+# Database
+DB_TYPE=mongo
+DB_URL=mongodb+srv://securepool-user:SecurePool%40123@cluster0.xxxxx.mongodb.net/securepool
+
+# JWT (paste the single-line output from Step 2)
+JWT_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAK...\n-----END RSA PRIVATE KEY-----\n
+JWT_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\nMIIBIjANBgk...\n-----END PUBLIC KEY-----\n
+
+# Email
+EMAIL_HOST=smtp.gmail.com
+EMAIL_PORT=587
+EMAIL_SECURE=false
+EMAIL_USER=demandon.ps@gmail.com
+EMAIL_PASS=hjggfnfiskzzrnuy
+EMAIL_FROM=demandon.ps@gmail.com
+
+# Server
+PORT=5001
+CORS_ORIGINS=*
+RATE_LIMIT_ENABLED=true
+```
+
+> Set `CORS_ORIGINS=*` for now. Update it after getting your Vercel frontend URL.
+
+### 3.4 Deploy
+
+Click **"Deploy"**. Railway builds and starts your server.
+
+### 3.5 Get Your Backend URL
+
+After deployment, Railway gives you a URL:
+
+```
+https://securepool-production.up.railway.app
+```
+
+### 3.6 Verify
+
+```bash
+curl https://securepool-production.up.railway.app/health
+# → {"status":"ok"}
+```
+
+Check Swagger docs:
+
+```
+https://securepool-production.up.railway.app/docs
+```
+
+---
+
+## Step 4: Deploy Frontend on Vercel
+
+### 4.1 Create Project
+
+1. Go to https://vercel.com
+2. Click **"Add New Project"**
+3. **Import** your GitHub repository
+
+### 4.2 Configure Build
+
+| Setting | Value |
+|---------|-------|
+| Framework Preset | Vite |
+| Root Directory | `apps/demo-frontend` |
+| Build Command | `cd ../.. && npm ci && npx turbo run build --filter=@securepool/react-sdk && cd apps/demo-frontend && npx vite build` |
+| Output Directory | `dist` |
+
+### 4.3 Add Environment Variable
+
+```env
+VITE_API_URL=https://securepool-production.up.railway.app
+```
+
+### 4.4 Deploy
+
+Click **"Deploy"**. Vercel builds the static React app.
+
+### 4.5 Get Your Frontend URL
+
+Vercel gives you:
+
+```
+https://securepool.vercel.app
+```
+
+### 4.6 Update CORS on Railway
+
+Go back to Railway → **Variables** → Update:
+
+```env
+CORS_ORIGINS=https://securepool.vercel.app
+```
+
+Railway auto-redeploys with the new CORS setting.
+
+### 4.7 Verify
+
+Open `https://securepool.vercel.app` — you should see the login page. Register a new account, check your email for OTP, and login.
+
+---
+
+## Step 5: Publish NPM Packages (Optional)
+
+This lets other developers install your library with `npm install @securepool/api`.
+
+### 5.1 Create npm Account
+
+1. Go to https://www.npmjs.com/signup
+2. Create an account
+
+### 5.2 Login from Terminal
+
+```bash
+npm login
+```
+
+### 5.3 Create npm Organization (for scoped packages)
+
+1. Go to https://www.npmjs.com/org/create
+2. Create organization named `securepool`
+3. This reserves the `@securepool/` scope
+
+### 5.4 Publish All Packages
+
+```bash
+cd securepool
+
+# Publish in dependency order
+cd packages/core && npm publish --access public && cd ../..
+cd packages/application && npm publish --access public && cd ../..
+cd packages/infrastructure && npm publish --access public && cd ../..
+cd packages/persistence && npm publish --access public && cd ../..
+cd packages/api && npm publish --access public && cd ../..
+cd packages/react-sdk && npm publish --access public && cd ../..
+```
+
+### 5.5 Verify
+
+```bash
+npm info @securepool/api
+npm info @securepool/react-sdk
+```
+
+### 5.6 How Others Use It
+
+**Their backend:**
+
+```bash
+npm install @securepool/api
+```
+
+```ts
+import { createSecurePool } from "@securepool/api";
+
+const { app } = await createSecurePool({
+  database: { type: "mongo", url: process.env.DB_URL },
+  jwt: { privateKey: "...", publicKey: "..." },
+});
+
+app.listen(3000);
+```
+
+**Their frontend:**
+
+```bash
+npm install @securepool/react-sdk
+```
+
+```tsx
+import { SecurePoolProvider, LoginForm } from "@securepool/react-sdk";
+
+<SecurePoolProvider config={{ apiBaseUrl: "https://api.example.com", tenantId: "default" }}>
+  <LoginForm />
+</SecurePoolProvider>
+```
+
+---
+
+## Alternative: Deploy with Docker
+
+If you prefer Docker (for AWS ECS, DigitalOcean, etc.):
+
+### Build
+
+```bash
+cd securepool
+docker build -f apps/demo-backend/Dockerfile -t securepool-api .
+```
+
+### Run
+
+```bash
+docker run -p 5001:5001 \
+  -e DB_TYPE=mongo \
+  -e DB_URL="mongodb+srv://..." \
+  -e JWT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..." \
+  -e JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n..." \
+  -e EMAIL_HOST=smtp.gmail.com \
+  -e EMAIL_PORT=587 \
+  -e EMAIL_SECURE=false \
+  -e EMAIL_USER=demandon.ps@gmail.com \
+  -e EMAIL_PASS=hjggfnfiskzzrnuy \
+  -e EMAIL_FROM=demandon.ps@gmail.com \
+  -e PORT=5001 \
+  -e CORS_ORIGINS="*" \
+  -e RATE_LIMIT_ENABLED=true \
+  securepool-api
+```
+
+### Push to Docker Hub
+
+```bash
+docker tag securepool-api yourusername/securepool-api:latest
+docker push yourusername/securepool-api:latest
+```
+
+---
+
+## Post-Deployment Checklist
+
+After deploying, verify everything works:
+
+- [ ] `GET /health` returns `{"status":"ok"}`
+- [ ] `GET /docs` shows Swagger UI
+- [ ] Register a new user (OTP email received)
+- [ ] Verify email with OTP
+- [ ] Login with email/password
+- [ ] Login with OTP
+- [ ] Forgot password flow works
+- [ ] Change password from dashboard
+- [ ] Sessions show up in dashboard
+- [ ] Multi-account switching works
+- [ ] `CORS_ORIGINS` is set to your Vercel URL (not `*`)
+
+---
+
+## Environment Variables Reference
+
+### Backend (Railway)
+
+| Variable | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `DB_TYPE` | Yes | `mongo` | Database type: `mongo` or `postgres` |
+| `DB_URL` | Yes | `mongodb+srv://...` | Database connection string |
+| `JWT_PRIVATE_KEY` | Yes | `-----BEGIN RSA...` | RSA private key (single line, `\n` for newlines) |
+| `JWT_PUBLIC_KEY` | Yes | `-----BEGIN PUBLIC...` | RSA public key (single line, `\n` for newlines) |
+| `EMAIL_HOST` | No | `smtp.gmail.com` | SMTP host |
+| `EMAIL_PORT` | No | `587` | SMTP port |
+| `EMAIL_SECURE` | No | `false` | Use TLS (`true` for port 465) |
+| `EMAIL_USER` | No | `you@gmail.com` | SMTP username |
+| `EMAIL_PASS` | No | `abcdefghijklmnop` | Gmail App Password |
+| `EMAIL_FROM` | No | `you@gmail.com` | Sender email address |
+| `PORT` | No | `5001` | Server port (Railway sets this automatically) |
+| `CORS_ORIGINS` | Yes | `https://app.vercel.app` | Allowed frontend origin |
+| `RATE_LIMIT_ENABLED` | No | `true` | Enable rate limiting |
+
+### Frontend (Vercel)
+
+| Variable | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `VITE_API_URL` | Yes | `https://api.railway.app` | Backend API URL |
+| `VITE_TENANT_ID` | No | `default` | Default tenant ID |
+
+---
+
+## Updating After Deployment
+
+### Push code changes
+
+```bash
+git add .
+git commit -m "your changes"
+git push
+```
+
+Railway and Vercel auto-redeploy on push.
+
+### Update npm packages
+
+```bash
+# Bump version in each package.json, then:
+cd packages/core && npm publish --access public
+# ... repeat for changed packages
+```
+
+---
+
+## Cost Summary
+
+| Service | Free Tier | Paid |
+|---------|-----------|------|
+| MongoDB Atlas | 512MB storage, shared cluster | $9/mo for dedicated |
+| Railway | 500 hours/month, 8GB RAM | $5/mo for always-on |
+| Vercel | Unlimited static sites | $20/mo for team features |
+| npm | Unlimited public packages | Free |
+
+**Total for hobby/MVP: $0/month**

package/README.md

@@ -0,0 +1,283 @@
+# SecurePool
+
+Production-grade, self-hosted authentication framework for Node.js and React. Plug-and-play JWT auth, OTP, Google SSO, multi-tenancy, session management — distributed as NPM packages.
+
+---
+
+## Run Locally (3 Commands)
+
+### Prerequisites
+
+| Tool | Required | Install |
+|------|----------|---------|
+| **Node.js 20+** | Yes | [nodejs.org](https://nodejs.org) |
+| **MongoDB 6+** | Yes | See below |
+| **Git** | Yes | Pre-installed on Mac. Windows: [git-scm.com](https://git-scm.com) |
+
+### Install MongoDB
+
+**macOS:**
+```bash
+brew tap mongodb/brew
+brew install mongodb-community
+brew services start mongodb-community
+```
+
+**Windows:**
+1. Download from https://www.mongodb.com/try/download/community
+2. Run the installer (choose "Complete" install)
+3. Check "Install MongoDB as a Service"
+4. Also install [mongosh](https://www.mongodb.com/try/download/shell)
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt-get install -y mongodb-org
+sudo systemctl start mongod
+sudo systemctl enable mongod
+```
+
+### Setup & Run
+
+```bash
+# Step 1: Clone and enter the project
+git clone <your-repo-url>
+cd securepool
+
+# Step 2: Run interactive setup (installs deps, generates keys, configures DB & email, builds)
+npm run setup
+
+# Step 3: Start both servers
+npm run start:backend     # Terminal 1 → API on http://localhost:5001
+npm run start:frontend    # Terminal 2 → UI on http://localhost:5173
+```
+
+That's it. Open http://localhost:5173 and register your first account.
+
+---
+
+## Database Support
+
+SecurePool supports **MongoDB** and **SQL databases** (PostgreSQL / MySQL). Switch with one config change:
+
+```ts
+// MongoDB
+createSecurePool({ database: { type: "mongo", url: "mongodb://..." } })
+
+// PostgreSQL
+createSecurePool({ database: { type: "postgres", url: "postgresql://..." } })
+```
+
+| Database | Guide | ORM | Migration needed? |
+|----------|-------|-----|-------------------|
+| MongoDB | [DATABASE_MONGODB.md](docs/DATABASE_MONGODB.md) | Mongoose | No (auto-creates collections) |
+| PostgreSQL | [DATABASE_SQL.md](docs/DATABASE_SQL.md) | Prisma | Yes (`prisma migrate dev`) |
+| MySQL | [DATABASE_SQL.md](docs/DATABASE_SQL.md) | Prisma | Yes (`prisma migrate dev`) |
+
+---
+
+## Documentation
+
+| Document | What it covers |
+|----------|---------------|
+| [SETUP.md](SETUP.md) | Local development — prerequisites, RSA keys, `.env`, running backend + frontend |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Why monorepo, packages vs apps, dependency flow, clean architecture layers |
+| [DEPLOYMENT.md](DEPLOYMENT.md) | Production — cloud DB, Railway (backend), Vercel (frontend), npm publishing, Docker |
+| [DATABASE_MONGODB.md](docs/DATABASE_MONGODB.md) | MongoDB — local setup, Atlas cloud, collections, indexes, monitoring |
+| [DATABASE_SQL.md](docs/DATABASE_SQL.md) | PostgreSQL / MySQL — local setup, cloud providers, Prisma migrations, schema details |
+
+---
+
+### What `npm run setup` Does
+
+The setup script runs on **Mac, Windows, and Linux** (it's a Node.js script, not bash). It will:
+
+1. Check prerequisites (Node.js, MongoDB, OpenSSL)
+2. Run `npm install`
+3. Generate RSA keys for JWT (`private.pem`, `public.pem`)
+4. Ask you to choose database mode (simple / with auth / custom URL)
+5. Optionally configure Gmail SMTP for OTP emails
+6. Create your `.env` file
+7. Build all 6 packages
+
+### URLs After Setup
+
+| URL | What |
+|-----|------|
+| http://localhost:5173 | Frontend — login, signup, dashboard |
+| http://localhost:5001/docs | Swagger API Docs — try all endpoints live |
+| http://localhost:5001/health | Health check |
+
+### Killing a Running Server
+
+If you get `EADDRINUSE` (port already in use):
+
+**macOS / Linux:**
+```bash
+lsof -ti:5001 | xargs kill -9
+```
+
+**Windows (PowerShell):**
+```powershell
+Get-Process -Id (Get-NetTCPConnection -LocalPort 5001).OwningProcess | Stop-Process -Force
+```
+
+---
+
+## Features
+
+- **JWT Authentication** — RS256-based access + refresh tokens with rotation
+- **OTP Login** — Email-based one-time passwords with expiry and attempt limits
+- **Email Verification** — OTP-verified registration (user created only after verification)
+- **Password Management** — Forgot password (OTP reset) + change password (authenticated)
+- **Google SSO** — Login with Google ID tokens
+- **Multi-Tenancy** — Tenant-isolated data via `x-tenant-id` header
+- **Session Management** — Device tracking, session listing, per-device revocation
+- **Multi-Account Switching** — Store multiple accounts, switch without re-login
+- **Role-Based Access Control** — RBAC middleware for route protection
+- **Multi-Database** — MongoDB (Mongoose) and PostgreSQL (Prisma) out of the box
+- **Rate Limiting** — Per-route rate limits (login, OTP, general)
+- **Audit Logging** — Tracks login, register, password reset, OTP events
+- **Swagger API Docs** — Interactive API explorer at `/docs`
+- **React SDK** — Provider, hooks, pre-built components (LoginForm, SignupForm, OTP, SessionList)
+
+---
+
+## Install as NPM Package
+
+**Backend:**
+
+```bash
+npm install @securepool/api
+```
+
+```ts
+import { createSecurePool } from "@securepool/api";
+
+const { app } = await createSecurePool({
+  database: { type: "mongo", url: "mongodb://localhost:27017/myapp" },
+  jwt: { privateKey: "...", publicKey: "..." },
+});
+
+app.listen(3000);
+// Auth endpoints ready: /auth/login, /auth/register, /sessions, etc.
+```
+
+**Frontend:**
+
+```bash
+npm install @securepool/react-sdk
+```
+
+```tsx
+import { SecurePoolProvider, LoginForm, useAuth } from "@securepool/react-sdk";
+
+function App() {
+  return (
+    <SecurePoolProvider config={{ apiBaseUrl: "http://localhost:3000", tenantId: "default" }}>
+      <LoginForm onSuccess={() => console.log("Logged in!")} />
+    </SecurePoolProvider>
+  );
+}
+```
+
+---
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| `@securepool/core` | Entities and enums (User, Role, Session, OTP, etc.) |
+| `@securepool/application` | Business logic, interfaces, AuthService |
+| `@securepool/infrastructure` | JWT, bcrypt, OTP, Nodemailer, Google SSO |
+| `@securepool/persistence` | MongoDB + PostgreSQL repository implementations |
+| `@securepool/api` | Express routes, middleware, `createSecurePool()` |
+| `@securepool/react-sdk` | React provider, `useAuth()` hook, UI components |
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Auth | Description |
+|--------|----------|------|-------------|
+| GET | `/health` | No | Health check |
+| GET | `/docs` | No | Swagger API documentation |
+| POST | `/auth/register` | No | Register + send verification OTP |
+| POST | `/auth/verify-email` | No | Verify OTP and create account |
+| POST | `/auth/login` | No | Login with email + password |
+| POST | `/auth/otp/request` | No | Request OTP for login |
+| POST | `/auth/otp/verify` | No | Verify OTP and login |
+| POST | `/auth/google` | No | Google SSO login |
+| POST | `/auth/refresh` | No | Refresh access token |
+| POST | `/auth/forgot-password` | No | Send password reset OTP |
+| POST | `/auth/reset-password` | No | Reset password with OTP |
+| POST | `/auth/change-password` | Yes | Change password (old + new) |
+| GET | `/sessions` | Yes | List active sessions |
+| DELETE | `/sessions/:id` | Yes | Revoke a session |
+| DELETE | `/sessions` | Yes | Revoke all sessions |
+
+All `/auth/*` routes require `x-tenant-id` header. Authenticated routes require `Authorization: Bearer <token>`.
+
+---
+
+## Project Structure
+
+```
+securepool/
+├── packages/              # NPM library packages (the product)
+│   ├── core/              # Entities, enums — zero dependencies
+│   ├── application/       # Interfaces, AuthService — business logic
+│   ├── infrastructure/    # JWT, bcrypt, OTP, email — implementations
+│   ├── persistence/       # MongoDB + PostgreSQL — database layer
+│   ├── api/               # Express server — routes, middleware, Swagger
+│   └── react-sdk/         # React — provider, hooks, UI components
+│
+├── apps/                  # Demo applications (for testing)
+│   ├── demo-backend/      # Example server using @securepool/api
+│   └── demo-frontend/     # Example React app using @securepool/react-sdk
+│
+├── scripts/
+│   └── setup.sh           # One-command setup script
+│
+├── docs/
+│   ├── DATABASE_MONGODB.md # MongoDB setup (local + Atlas)
+│   └── DATABASE_SQL.md     # PostgreSQL / MySQL setup (local + cloud)
+│
+├── SETUP.md               # Local development guide
+├── ARCHITECTURE.md         # Code structure and design decisions
+├── DEPLOYMENT.md           # Production deployment guide
+└── README.md              # This file
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run setup` | Interactive first-time setup (DB, keys, email, build) |
+| `npm run build` | Build all packages |
+| `npm run start:backend` | Start API server on port 5001 |
+| `npm run start:frontend` | Start React app on port 5173 |
+| `npm run clean` | Delete all dist folders |
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Runtime | Node.js 20+ |
+| Language | TypeScript (strict mode) |
+| Backend Framework | Express.js |
+| Database | MongoDB (Mongoose) / PostgreSQL (Prisma) |
+| Authentication | JWT (RS256), bcrypt, OTP |
+| Email | Nodemailer (Gmail SMTP) |
+| Frontend | React 19, React Router |
+| Build System | Turborepo + npm workspaces |
+| API Docs | Swagger UI (OpenAPI 3.0) |
+
+---
+
+## License
+
+MIT