securepool 1.0.0

package/docs/DATABASE_SQL.md

@@ -0,0 +1,472 @@
+# SecurePool — PostgreSQL / MySQL Setup Guide
+
+This guide covers using SecurePool with **PostgreSQL** or **MySQL** via Prisma ORM.
+
+---
+
+## How It Works
+
+SecurePool uses **Prisma** as the ORM for SQL databases. When you set `type: "postgres"`, the persistence layer uses Prisma Client to interact with your SQL database.
+
+```ts
+createSecurePool({
+  database: {
+    type: "postgres",
+    url: "postgresql://user:password@localhost:5432/securepool"
+  },
+  ...
+})
+```
+
+Unlike MongoDB, SQL databases **require a migration step** to create tables before first use.
+
+---
+
+## PostgreSQL
+
+### Option 1: Local PostgreSQL (Development)
+
+#### Install
+
+```bash
+# macOS
+brew install postgresql@16
+brew services start postgresql@16
+```
+
+#### Create Database and User
+
+```bash
+# Connect as default user
+psql postgres
+```
+
+```sql
+-- Create database
+CREATE DATABASE securepool;
+
+-- Create user with password
+CREATE USER securepool_user WITH PASSWORD 'SecurePool@123';
+
+-- Grant privileges
+GRANT ALL PRIVILEGES ON DATABASE securepool TO securepool_user;
+
+-- Connect to the database and grant schema access
+\c securepool
+GRANT ALL ON SCHEMA public TO securepool_user;
+
+\q
+```
+
+#### Verify Connection
+
+```bash
+psql "postgresql://securepool_user:SecurePool%40123@localhost:5432/securepool"
+```
+
+#### .env Configuration
+
+```env
+DB_TYPE=postgres
+DB_URL=postgresql://securepool_user:SecurePool%40123@localhost:5432/securepool
+```
+
+---
+
+### Option 2: Cloud PostgreSQL (Production)
+
+#### Supabase (Free tier — recommended)
+
+1. Go to https://supabase.com → Create new project
+2. Go to **Settings** → **Database** → **Connection string**
+3. Copy the URI (starts with `postgresql://`)
+
+```env
+DB_TYPE=postgres
+DB_URL=postgresql://postgres:your-password@db.xxxx.supabase.co:5432/postgres
+```
+
+#### AWS RDS
+
+1. Create an RDS PostgreSQL instance
+2. Use the endpoint provided by AWS
+
+```env
+DB_TYPE=postgres
+DB_URL=postgresql://admin:password@your-instance.region.rds.amazonaws.com:5432/securepool
+```
+
+#### Railway (built-in PostgreSQL)
+
+1. In your Railway project, click **"+ New"** → **"Database"** → **"PostgreSQL"**
+2. Railway auto-sets `DATABASE_URL`
+
+```env
+DB_TYPE=postgres
+DB_URL=${{ Postgres.DATABASE_URL }}
+```
+
+#### Neon (serverless PostgreSQL)
+
+1. Go to https://neon.tech → Create project
+2. Copy the connection string
+
+```env
+DB_TYPE=postgres
+DB_URL=postgresql://user:pass@ep-xxx.region.aws.neon.tech/securepool?sslmode=require
+```
+
+---
+
+## MySQL
+
+### Change Prisma Schema Provider
+
+By default, the Prisma schema is set to `postgresql`. To use MySQL, update the schema:
+
+Edit `packages/persistence/prisma/schema.prisma`:
+
+```prisma
+datasource db {
+  provider = "mysql"
+  url      = env("DATABASE_URL")
+}
+```
+
+### Install MySQL
+
+```bash
+# macOS
+brew install mysql
+brew services start mysql
+```
+
+### Create Database and User
+
+```bash
+mysql -u root
+```
+
+```sql
+CREATE DATABASE securepool;
+CREATE USER 'securepool_user'@'localhost' IDENTIFIED BY 'SecurePool@123';
+GRANT ALL PRIVILEGES ON securepool.* TO 'securepool_user'@'localhost';
+FLUSH PRIVILEGES;
+EXIT;
+```
+
+### .env Configuration
+
+```env
+DB_TYPE=postgres
+DB_URL=mysql://securepool_user:SecurePool%40123@localhost:3306/securepool
+```
+
+> Note: Even though it's MySQL, use `DB_TYPE=postgres` because SecurePool uses Prisma for all SQL databases. The `postgres` type tells SecurePool to use the Prisma code path (not MongoDB).
+
+### Cloud MySQL Options
+
+| Provider | URL Format |
+|---|---|
+| PlanetScale | `mysql://user:pass@region.connect.psdb.cloud/securepool?sslaccept=strict` |
+| AWS RDS MySQL | `mysql://admin:pass@instance.region.rds.amazonaws.com:3306/securepool` |
+| DigitalOcean | `mysql://user:pass@db-mysql-xxx.ondigitalocean.com:25060/securepool?ssl-mode=REQUIRED` |
+
+---
+
+## Running Migrations (Required for SQL)
+
+After setting your `DB_URL`, you must run Prisma migrations to create the tables.
+
+### First Time Setup
+
+```bash
+cd packages/persistence
+
+# Set the DATABASE_URL for Prisma
+export DATABASE_URL="postgresql://securepool_user:SecurePool%40123@localhost:5432/securepool"
+
+# Generate Prisma Client
+npx prisma generate
+
+# Create and run migration
+npx prisma migrate dev --name init
+```
+
+### Production Migration
+
+```bash
+export DATABASE_URL="postgresql://user:pass@production-host:5432/securepool"
+npx prisma migrate deploy
+```
+
+### View Database in Prisma Studio (GUI)
+
+```bash
+cd packages/persistence
+export DATABASE_URL="postgresql://..."
+npx prisma studio
+```
+
+Opens a web UI at http://localhost:5555 to browse your data.
+
+---
+
+## Database Schema
+
+Prisma creates these tables automatically during migration:
+
+### Tables
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│    users      │     │    roles      │     │  user_roles   │
+├──────────────┤     ├──────────────┤     ├──────────────┤
+│ id (PK)       │     │ id (PK)       │     │ userId (FK)   │
+│ tenantId      │◄───┐│ name          │◄───┐│ roleId (FK)   │
+│ email         │    ││               │    │└──────────────┘
+│ passwordHash  │    │└──────────────┘    │
+│ isVerified    │    │                     │
+│ createdAt     │    │┌──────────────┐    │
+└──────────────┘    ││ sessions      │    │
+                     │├──────────────┤    │
+                     ││ id (PK)       │    │
+                     ├│ userId (FK)   │    │
+                     ││ device        │    │
+                     ││ ip            │    │
+                     ││ createdAt     │    │
+                     ││ isActive      │    │
+                     │└──────────────┘    │
+                     │                     │
+                     │┌──────────────┐    │
+                     ││ audit_logs    │    │
+                     │├──────────────┤    │
+                     ││ id (PK)       │    │
+                     └│ userId (FK)   │    │
+                      │ tenantId      │    │
+                      │ action        │    │
+                      │ ip            │    │
+                      │ metadata (JSON│    │
+                      │ timestamp     │    │
+                      └──────────────┘    │
+                                           │
+┌──────────────┐     ┌──────────────┐     │
+│refresh_tokens │     │ otp_codes     │     │
+├──────────────┤     ├──────────────┤     │
+│ id (PK)       │     │ id (PK)       │     │
+│ userId        │     │ userId        │     │
+│ tokenHash     │     │ code          │     │
+│ expiresAt     │     │ expiresAt     │     │
+│ isRevoked     │     │ attempts      │     │
+└──────────────┘     └──────────────┘     │
+```
+
+### Column Details
+
+**users**
+
+| Column | Type | Constraints |
+|---|---|---|
+| id | UUID | Primary key, auto-generated |
+| tenantId | String | Indexed |
+| email | String | Unique per tenant (`email + tenantId`) |
+| passwordHash | String? | Nullable (Google SSO users have no password) |
+| isVerified | Boolean | Default: false |
+| createdAt | DateTime | Default: now() |
+
+**roles**
+
+| Column | Type | Constraints |
+|---|---|---|
+| id | UUID | Primary key |
+| name | String | Unique (e.g., "admin", "user") |
+
+**user_roles** (junction table)
+
+| Column | Type | Constraints |
+|---|---|---|
+| userId | UUID | FK → users.id, cascade delete |
+| roleId | UUID | FK → roles.id, cascade delete |
+| | | Composite PK: (userId, roleId) |
+
+**refresh_tokens**
+
+| Column | Type | Constraints |
+|---|---|---|
+| id | UUID | Primary key |
+| userId | String | Indexed |
+| tokenHash | String | Indexed (for fast lookup) |
+| expiresAt | DateTime | Token expiry (30 days) |
+| isRevoked | Boolean | Default: false |
+
+**otp_codes**
+
+| Column | Type | Constraints |
+|---|---|---|
+| id | UUID | Primary key |
+| userId | String | Indexed |
+| code | String | 6-digit code |
+| expiresAt | DateTime | Code expiry (10 minutes) |
+| attempts | Int | Default: 0 (max 3 attempts) |
+
+**sessions**
+
+| Column | Type | Constraints |
+|---|---|---|
+| id | UUID | Primary key |
+| userId | String | FK → users.id, indexed |
+| device | String | e.g., "Chrome on Mac OS" |
+| ip | String | Client IP address |
+| createdAt | DateTime | Default: now() |
+| isActive | Boolean | Default: true |
+
+**audit_logs**
+
+| Column | Type | Constraints |
+|---|---|---|
+| id | UUID | Primary key |
+| userId | String | FK → users.id, indexed |
+| tenantId | String | Indexed |
+| action | String | e.g., "LOGIN_SUCCESS", "REGISTER" |
+| ip | String | Client IP |
+| metadata | JSON | Additional data |
+| timestamp | DateTime | Default: now() |
+
+---
+
+## PostgreSQL URL Format Reference
+
+| Scenario | URL Format |
+|---|---|
+| Local | `postgresql://user:pass@localhost:5432/securepool` |
+| With SSL | `postgresql://user:pass@host:5432/securepool?sslmode=require` |
+| Supabase | `postgresql://postgres:pass@db.xxx.supabase.co:5432/postgres` |
+| AWS RDS | `postgresql://admin:pass@instance.region.rds.amazonaws.com:5432/securepool` |
+| Neon | `postgresql://user:pass@ep-xxx.neon.tech/securepool?sslmode=require` |
+| Railway | Auto-set via `${{ Postgres.DATABASE_URL }}` |
+
+---
+
+## Switching from MongoDB to PostgreSQL
+
+If you're already running SecurePool with MongoDB and want to switch:
+
+### Step 1: Update `.env`
+
+```env
+# Before (MongoDB)
+DB_TYPE=mongo
+DB_URL=mongodb://localhost:27017/securepool
+
+# After (PostgreSQL)
+DB_TYPE=postgres
+DB_URL=postgresql://securepool_user:SecurePool%40123@localhost:5432/securepool
+```
+
+### Step 2: Run Migrations
+
+```bash
+cd packages/persistence
+export DATABASE_URL="postgresql://securepool_user:SecurePool%40123@localhost:5432/securepool"
+npx prisma migrate dev --name init
+```
+
+### Step 3: Restart Backend
+
+```bash
+cd apps/demo-backend
+npx ts-node src/index.ts
+```
+
+That's it. No code changes needed. All auth features (login, OTP, sessions, etc.) work the same way.
+
+### Data Migration
+
+SecurePool does **not** auto-migrate data between databases. If you need to move existing users from MongoDB to PostgreSQL, you'll need to export from Mongo and import to PostgreSQL manually.
+
+---
+
+## Backup & Restore
+
+### PostgreSQL
+
+```bash
+# Backup
+pg_dump "postgresql://user:pass@localhost:5432/securepool" > backup.sql
+
+# Restore
+psql "postgresql://user:pass@localhost:5432/securepool" < backup.sql
+```
+
+### MySQL
+
+```bash
+# Backup
+mysqldump -u securepool_user -p securepool > backup.sql
+
+# Restore
+mysql -u securepool_user -p securepool < backup.sql
+```
+
+---
+
+## Troubleshooting
+
+### "relation does not exist"
+
+Migrations haven't been run:
+
+```bash
+cd packages/persistence
+npx prisma migrate dev
+```
+
+### "authentication failed for user"
+
+Check your credentials and ensure the user has access to the database:
+
+```bash
+psql "postgresql://user:pass@localhost:5432/securepool"
+```
+
+### "SSL required"
+
+Cloud providers often require SSL. Add to your URL:
+
+```
+?sslmode=require
+```
+
+### "Prisma Client not generated"
+
+```bash
+cd packages/persistence
+npx prisma generate
+```
+
+### Reset database (delete all data)
+
+```bash
+cd packages/persistence
+npx prisma migrate reset
+```
+
+> Warning: This deletes ALL data. Use only in development.
+
+---
+
+## Comparison: MongoDB vs PostgreSQL
+
+| Feature | MongoDB | PostgreSQL |
+|---|---|---|
+| Setup complexity | Easier (no migrations) | Requires `prisma migrate` |
+| Schema enforcement | Flexible (schemaless) | Strict (type-safe) |
+| Joins | Manual (application-level) | Native SQL joins |
+| Transactions | Supported (4.0+) | Full ACID support |
+| JSON support | Native (BSON) | JSONB column type |
+| Best for | Rapid prototyping, flexibility | Data integrity, complex queries |
+| Free cloud | Atlas M0 (512MB) | Supabase (500MB), Neon (512MB) |
+| ORM used | Mongoose | Prisma |
+| Code changes needed | None | None |
+
+Both are fully supported. Choose based on your team's preference and requirements.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "securepool",
+"version": "1.0.0",
+  "packageManager": "npm@11.6.2",
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ],
+  "scripts": {
+    "setup": "node scripts/setup.js",
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "clean": "turbo run clean",
+    "start:backend": "cd apps/demo-backend && npx ts-node src/index.ts",
+    "start:frontend": "cd apps/demo-frontend && npx vite"
+  },
+  "devDependencies": {
+    "turbo": "^2.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/packages/api/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@securepool/api",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@securepool/core": "1.0.0",
+    "@securepool/application": "1.0.0",
+    "@securepool/infrastructure": "1.0.0",
+    "@securepool/persistence": "1.0.0",
+    "express": "^4.21.0",
+    "cors": "^2.8.5",
+    "express-rate-limit": "^7.4.0",
+    "helmet": "^7.1.0",
+    "ua-parser-js": "^1.0.38",
+    "dotenv": "^16.4.5",
+    "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17",
+    "@types/ua-parser-js": "^0.7.39",
+    "@types/swagger-ui-express": "^4.1.6"
+  }
+}

package/packages/api/src/createSecurePool.ts

@@ -0,0 +1,113 @@
+import express, { Express } from "express";
+import cors from "cors";
+import helmet from "helmet";
+import { AuthService, RefreshTokenService } from "@securepool/application";
+import { JwtTokenService, BcryptHasher, OtpServiceImpl, GoogleAuthServiceImpl, NodemailerEmailService } from "@securepool/infrastructure";
+import { createRepositories } from "@securepool/persistence";
+import { createAuthMiddleware } from "./middleware/authMiddleware";
+import { createAuthorize } from "./middleware/authorize";
+import { tenantMiddleware } from "./middleware/tenantMiddleware";
+import { apiRateLimiter } from "./middleware/rateLimiter";
+import { createAuthRoutes } from "./routes/authRoutes";
+import { createSessionRoutes } from "./routes/sessionRoutes";
+import { setupSwagger } from "./swagger";
+
+export interface SecurePoolConfig {
+  database: {
+    type: "mongo" | "postgres";
+    url: string;
+  };
+  jwt: {
+    privateKey: string;
+    publicKey: string;
+    accessTokenExpirySeconds?: number;
+  };
+  google?: {
+    clientId: string;
+  };
+  otp?: {
+    maxAttempts?: number;
+    expiryMinutes?: number;
+  };
+  email?: {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    pass: string;
+    from: string;
+  };
+  security?: {
+    enableRateLimit?: boolean;
+    corsOrigins?: string | string[];
+  };
+}
+
+export async function createSecurePool(config: SecurePoolConfig) {
+  // Initialize repositories
+  const repos = await createRepositories(config.database);
+
+  // Initialize infrastructure services
+  const hasher = new BcryptHasher();
+  const tokenService = new JwtTokenService(config.jwt.privateKey, config.jwt.publicKey, config.jwt.accessTokenExpirySeconds);
+
+  const otpService = config.otp !== undefined
+    ? new OtpServiceImpl(repos.otpRepo, config.otp)
+    : new OtpServiceImpl(repos.otpRepo);
+
+  const googleAuthService = config.google
+    ? new GoogleAuthServiceImpl(config.google.clientId)
+    : undefined;
+
+  // Initialize email service
+  const emailService = config.email
+    ? new NodemailerEmailService({
+        host: config.email.host,
+        port: config.email.port,
+        secure: config.email.secure,
+        auth: { user: config.email.user, pass: config.email.pass },
+        from: config.email.from,
+      })
+    : undefined;
+
+  // Initialize application services
+  const authService = new AuthService(repos.userRepo, hasher, tokenService, repos.tokenRepo, otpService, repos.auditLogRepo, emailService);
+  const refreshTokenService = new RefreshTokenService(repos.tokenRepo, tokenService);
+
+  // Create Express app
+  const app: Express = express();
+  app.use(express.json());
+  app.use(helmet({
+    contentSecurityPolicy: false, // Allow Swagger UI to load
+    crossOriginEmbedderPolicy: false,
+  }));
+  app.use(cors({ origin: config.security?.corsOrigins || "*" }));
+
+  if (config.security?.enableRateLimit !== false) {
+    app.use(apiRateLimiter);
+  }
+
+  // Middleware factories
+  const authMiddleware = createAuthMiddleware(tokenService);
+  const authorize = createAuthorize(repos.roleRepo);
+
+  // Routes
+  app.use("/auth", tenantMiddleware, createAuthRoutes(authService, refreshTokenService, repos.sessionRepo, repos.auditLogRepo, tokenService, authMiddleware));
+  app.use("/sessions", authMiddleware, createSessionRoutes(repos.sessionRepo));
+
+  // Health check
+  app.get("/health", (_req, res) => { res.json({ status: "ok" }); });
+
+  // Swagger API docs
+  setupSwagger(app);
+
+  return {
+    app,
+    authService,
+    refreshTokenService,
+    authMiddleware,
+    authorize,
+    tokenService,
+    repositories: repos,
+  };
+}

package/packages/api/src/index.ts

@@ -0,0 +1,8 @@
+export { createSecurePool, SecurePoolConfig } from "./createSecurePool";
+export { createAuthMiddleware, AuthenticatedRequest } from "./middleware/authMiddleware";
+export { tenantMiddleware } from "./middleware/tenantMiddleware";
+export { createAuthorize } from "./middleware/authorize";
+export { loginRateLimiter, apiRateLimiter, otpRateLimiter } from "./middleware/rateLimiter";
+export { createAuthRoutes } from "./routes/authRoutes";
+export { createSessionRoutes } from "./routes/sessionRoutes";
+export { setupSwagger } from "./swagger";

package/packages/api/src/middleware/authMiddleware.ts

@@ -0,0 +1,26 @@
+import { Request, Response, NextFunction } from "express";
+import { ITokenService } from "@securepool/application";
+
+export interface AuthenticatedRequest extends Request {
+  user?: { userId: string; tenantId: string };
+  tenantId?: string;
+}
+
+export function createAuthMiddleware(tokenService: ITokenService) {
+  return async (req: AuthenticatedRequest, res: Response, next: NextFunction): Promise<void> => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      res.status(401).json({ error: "Missing or invalid authorization header" });
+      return;
+    }
+
+    const token = authHeader.split(" ")[1];
+    try {
+      const payload = await tokenService.verifyAccessToken(token);
+      req.user = { userId: payload.sub, tenantId: payload.tenantId };
+      next();
+    } catch {
+      res.status(401).json({ error: "Invalid or expired token" });
+    }
+  };
+}

package/packages/api/src/middleware/authorize.ts

@@ -0,0 +1,24 @@
+import { Response, NextFunction } from "express";
+import { AuthenticatedRequest } from "./authMiddleware";
+import { IRoleRepository } from "@securepool/application";
+
+export function createAuthorize(roleRepo: IRoleRepository) {
+  return (allowedRoles: string[]) => {
+    return async (req: AuthenticatedRequest, res: Response, next: NextFunction): Promise<void> => {
+      if (!req.user) {
+        res.status(401).json({ error: "Not authenticated" });
+        return;
+      }
+
+      const userRoles = await roleRepo.getUserRoles(req.user.userId);
+      const hasRole = userRoles.some(role => allowedRoles.includes(role.name));
+
+      if (!hasRole) {
+        res.status(403).json({ error: "Forbidden: insufficient permissions" });
+        return;
+      }
+
+      next();
+    };
+  };
+}