create-simo-api 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# create-simo-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffold an Express 5 + PostgreSQL API pre-configured with:
+
+- **JWT auth**: access token + refresh token in an `httpOnly` cookie, stored hashed, rotated on every refresh, reuse detection
+- **Role permissions** with `authorize('PERMISSION')`
+- **Zod** validation for request bodies, params and `.env`
+- **Service layer** (routes → controllers → services → models)
+- Central **error handling** (`AppError`, JSON 404, PostgreSQL errors)
+- **Migrations** (`node-pg-migrate`), admin **seed**, **rate limiting**, **morgan** logs
+- **Tests** with Supertest
+- Example resources: users and products
+
+## Usage
+
+```bash
+npm create simo-api@latest my-api
+cd my-api
+# set DATABASE_URL in .env
+npm run migrate:up
+npm run seed
+npm run dev
+```
+
+`.env` is generated with random JWT secrets and a random admin password.
+
+## Requirements
+
+- Node.js 20+
+- PostgreSQL
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE_DIR = join(__dirname, 'template')
+
+const RENAME = {
+  _gitignore: '.gitignore',
+  '_env.example': '.env.example',
+}
+
+function fail(msg) {
+  console.error(`\n  ✖ ${msg}\n`)
+  process.exit(1)
+}
+
+function main() {
+  const projectName = process.argv[2]
+
+  if (!projectName) {
+    fail('Usage: npm create simo-api@latest <project-name>')
+  }
+
+  const targetDir = resolve(process.cwd(), projectName)
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+    fail(`Directory "${projectName}" already exists and is not empty.`)
+  }
+
+  console.log(`\n  Scaffolding project in ${targetDir} ...`)
+
+  mkdirSync(targetDir, { recursive: true })
+  cpSync(TEMPLATE_DIR, targetDir, { recursive: true })
+
+  for (const [from, to] of Object.entries(RENAME)) {
+    const src = join(targetDir, from)
+    if (existsSync(src)) renameSync(src, join(targetDir, to))
+  }
+
+  const pkgPath = join(targetDir, 'package.json')
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  pkg.name = projectName
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+
+  const env = readFileSync(join(targetDir, '.env.example'), 'utf8')
+    .replace(/^ACCESS_TOKEN_SECRET=$/m, `ACCESS_TOKEN_SECRET=${randomBytes(64).toString('hex')}`)
+    .replace(/^REFRESH_TOKEN_SECRET=$/m, `REFRESH_TOKEN_SECRET=${randomBytes(64).toString('hex')}`)
+    .replace(/^ADMIN_PASSWORD=$/m, `ADMIN_PASSWORD=${randomBytes(12).toString('base64url')}`)
+  writeFileSync(join(targetDir, '.env'), env)
+
+  console.log('  Installing dependencies with npm ...\n')
+  const install = spawnSync('npm', ['install'], { cwd: targetDir, stdio: 'inherit' })
+
+  if (install.status !== 0) {
+    fail('Dependency installation failed. You can cd into the folder and run "npm install" manually.')
+  }
+
+  console.log(`
+  ✔ Done! Project created.
+
+  Next steps:
+    cd ${projectName}
+    # set DATABASE_URL in .env
+    npm run migrate:up
+    npm run seed
+    npm run dev
+`)
+}
+
+main()

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "create-simo-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Scaffold an Express 5 + PostgreSQL API with JWT auth (access + refresh rotation), role permissions, Zod validation, service layer, migrations, seed and tests.",
+  "type": "module",
+  "bin": {
+    "create-simo-api": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "keywords": [
+    "express",
+    "postgresql",
+    "jwt",
+    "api",
+    "boilerplate",
+    "scaffold",
+    "create"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/README.md

@@ -0,0 +1,61 @@
+# Simo API
+
+API Express 5 + PostgreSQL.
+
+## Démarrage
+
+```bash
+npm install
+cp .env.example .env      # si .env n'existe pas, puis remplir DATABASE_URL
+npm run migrate:up
+npm run seed              # crée l'admin du .env
+npm run dev
+```
+
+Générer un secret JWT :
+
+```bash
+node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
+```
+
+## Structure
+
+```
+app.js           app Express (middlewares, routes)
+index.js         lance le serveur
+config/          env (validé avec Zod), db, permissions
+routes/          auth, user, product
+controllers/     req/res seulement
+services/        logique métier
+models/          requêtes SQL
+middlewares/     auth, authorize, validate, rateLimit, errors
+validations/     schémas Zod
+utils/           AppError, verifyToken
+migrations/
+seeds/
+tests/
+```
+
+## Routes
+
+| Route | Accès |
+|---|---|
+| `POST /api/auth/register` · `login` | public |
+| `POST /api/auth/refresh` · `logout` | cookie `refreshToken` |
+| `GET /api/user/me` | connecté |
+| `GET /api/user/getAll` | admin |
+| `POST /api/user/create` | connecté (seul l'admin choisit le rôle) |
+| `GET /api/product/getAll` · `/:id` | public |
+| `POST /api/product/create` | admin |
+| `PATCH /api/product/update/:id` | admin |
+| `DELETE /api/product/delete/:id` | admin |
+
+## Fonctionnement
+
+- **Auth** : access token JWT (`ACCESS_TOKEN_EXPIRES_IN`, 15m par défaut) dans `Authorization: Bearer`, refresh token (`REFRESH_TOKEN_EXPIRES_DAYS`, 7 j par défaut) en cookie `httpOnly`, stocké hashé dans `refresh_tokens`. Rotation à chaque refresh ; un token réutilisé révoque toutes les sessions de l'utilisateur.
+- **Permissions** : `authorize('PERMISSION')` sur la route, rôles autorisés dans `config/permissions.js`.
+- **Validation** : `validate(schema)` pour le body, `validate(schema, 'params')` pour les paramètres.
+- **Erreurs** : `throw new AppError(message, status)` dans les controllers (pas de try/catch). `errorHandler` renvoie du JSON, convertit les erreurs PostgreSQL (doublon → 409) et renvoie 404 pour les routes inconnues.
+- **Env** : le serveur refuse de démarrer si une variable manque ou est invalide.
+- **Logs** : morgan (`dev` en développement, `combined` en production).
+- **Rate limit** : 100 requêtes / 15 min par IP sur `/api`.

package/template/_env.example

@@ -0,0 +1,15 @@
+NODE_ENV=development
+PORT=3000
+
+DATABASE_URL=postgres://user:password@localhost:5432/dbname
+
+CORS_ORIGIN=http://localhost:5173
+
+ACCESS_TOKEN_SECRET=
+REFRESH_TOKEN_SECRET=
+ACCESS_TOKEN_EXPIRES_IN=15m
+REFRESH_TOKEN_EXPIRES_DAYS=7
+
+ADMIN_NAME=Admin
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=

package/template/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+.env
+*.log
+coverage

package/template/app.js

@@ -0,0 +1,29 @@
+import express from 'express';
+import cors from 'cors';
+import cookieParser from 'cookie-parser';
+import morgan from 'morgan';
+import env from './config/env.js';
+import routes from './routes/index.js';
+import { notFound, errorHandler } from './middlewares/errorMiddleware.js';
+import { apiLimiter } from './middlewares/rateLimitMiddleware.js';
+
+const app = express();
+
+if (env.NODE_ENV !== 'test') {
+    app.use(morgan(env.NODE_ENV === 'production' ? 'combined' : 'dev'));
+}
+app.use(express.json());
+app.use(cookieParser());
+
+app.use(cors({ origin: env.CORS_ORIGIN, credentials: true }));
+
+app.get('/', (req, res) => {
+    res.send('API is running...');
+});
+
+app.use('/api', apiLimiter, routes);
+
+app.use(notFound);
+app.use(errorHandler);
+
+export default app;

package/template/config/db.js

@@ -0,0 +1,6 @@
+import pg from 'pg';
+import env from './env.js';
+
+const { Pool } = pg;
+
+export default new Pool({ connectionString: env.DATABASE_URL });

package/template/config/env.js

@@ -0,0 +1,27 @@
+import 'dotenv/config';
+import { z } from 'zod';
+
+const envSchema = z.object({
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    PORT: z.coerce.number().int().positive().default(3000),
+    DATABASE_URL: z.url(),
+    ACCESS_TOKEN_SECRET: z.string().min(32),
+    REFRESH_TOKEN_SECRET: z.string().min(32),
+    ACCESS_TOKEN_EXPIRES_IN: z.string().regex(/^\d+(ms|s|m|h|d)$/, 'Use a duration like 15m, 1h or 1d').default('15m'),
+    REFRESH_TOKEN_EXPIRES_DAYS: z.coerce.number().int().positive().default(7),
+    CORS_ORIGIN: z.string().min(1).transform((value) => value.split(',').map((origin) => origin.trim())),
+});
+
+const result = envSchema.safeParse(process.env);
+
+if (!result.success) {
+    console.error('Invalid environment variables:');
+    for (const issue of result.error.issues) {
+        console.error(`  - ${issue.path.join('.')}: ${issue.message}`);
+    }
+    process.exit(1);
+}
+
+const env = result.data;
+
+export default env;

package/template/config/permissions.js

@@ -0,0 +1,15 @@
+export const ROLES = {
+  ADMIN: 'admin',
+  USER: 'user'
+};
+
+
+export const PERMISSIONS = {
+    USER_CREATE: [ROLES.ADMIN, ROLES.USER],
+    USER_DELETE: [ROLES.ADMIN],
+    USER_GETALL: [ROLES.ADMIN],
+    PRODUCT_CREATE: [ROLES.ADMIN],
+    PRODUCT_UPDATE: [ROLES.ADMIN],
+    PRODUCT_DELETE: [ROLES.ADMIN],
+    PRODUCT_GETALL: [ROLES.ADMIN, ROLES.USER]
+}

package/template/controllers/authController.js

@@ -0,0 +1,53 @@
+import authService, { REFRESH_TOKEN_MAX_AGE } from '../services/authService.js';
+import env from '../config/env.js';
+
+const refreshCookieOptions = {
+    httpOnly: true,
+    secure: env.NODE_ENV === "production",
+    sameSite: "strict",
+    path: "/api/auth",
+};
+
+const sendRefreshCookie = (res, token) => {
+    res.cookie("refreshToken", token, {
+        ...refreshCookieOptions,
+        maxAge: REFRESH_TOKEN_MAX_AGE
+    });
+};
+
+const login = async (req, res) => {
+    const { accessToken, refreshToken, user } = await authService.login(req.body.email, req.body.password);
+    sendRefreshCookie(res, refreshToken);
+    res.status(200).json({ message: 'Login successful', accessToken, user });
+};
+
+const register = async (req, res) => {
+    const userId = await authService.register(req.body);
+    res.status(201).json({ message: 'User registered successfully', userId });
+};
+
+const refresh = async (req, res) => {
+    const { accessToken, refreshToken } = await authService.refresh(req.cookies.refreshToken);
+    sendRefreshCookie(res, refreshToken);
+    res.status(200).json({ accessToken });
+};
+
+const clearRefreshCookieOnError = (err, req, res, next) => {
+    res.clearCookie("refreshToken", refreshCookieOptions);
+    next(err);
+};
+
+const logout = async (req, res) => {
+    await authService.logout(req.cookies.refreshToken);
+    res.clearCookie("refreshToken", refreshCookieOptions);
+    res.status(200).json({ message: 'Logged out' });
+};
+
+
+export default {
+    login,
+    register,
+    refresh,
+    clearRefreshCookieOnError,
+    logout
+};

package/template/controllers/productController.js

@@ -0,0 +1,34 @@
+import productService from '../services/productService.js';
+
+const getAllProducts = async (req, res) => {
+    const products = await productService.getAll();
+    res.status(200).json({ products });
+};
+
+const getProductById = async (req, res) => {
+    const product = await productService.getById(req.params.id);
+    res.status(200).json({ product });
+};
+
+const createProduct = async (req, res) => {
+    const product = await productService.create(req.body);
+    res.status(201).json({ message: 'Product created successfully', product });
+};
+
+const updateProduct = async (req, res) => {
+    const product = await productService.update(req.params.id, req.body);
+    res.status(200).json({ message: 'Product updated successfully', product });
+};
+
+const deleteProduct = async (req, res) => {
+    await productService.remove(req.params.id);
+    res.status(200).json({ message: 'Product deleted successfully' });
+};
+
+export default {
+    getAllProducts,
+    getProductById,
+    createProduct,
+    updateProduct,
+    deleteProduct
+};

package/template/controllers/userController.js

@@ -0,0 +1,22 @@
+import userService from '../services/userService.js';
+
+const getAllUsers = async (req, res) => {
+    const users = await userService.getAll();
+    res.status(200).json({ users });
+};
+
+const getMe = async (req, res) => {
+    const user = await userService.getById(req.user.id);
+    res.status(200).json({ user });
+};
+
+const createUser = async (req, res) => {
+    const userId = await userService.create(req.body, req.user);
+    res.status(201).json({ message: 'User created successfully', userId });
+};
+
+export default {
+    getAllUsers,
+    getMe,
+    createUser
+};

package/template/index.js

@@ -0,0 +1,6 @@
+import env from './config/env.js';
+import app from './app.js';
+
+app.listen(env.PORT, () => {
+    console.log(`Server is running on port ${env.PORT}`);
+});

package/template/middlewares/authMiddleware.js

@@ -0,0 +1,15 @@
+import env from '../config/env.js';
+import AppError from '../utils/AppError.js';
+import verifyToken from '../utils/verifyToken.js';
+
+const authenticate = (req, res, next) => {
+    const header = req.headers.authorization;
+    if (!header?.startsWith('Bearer ')) {
+        throw new AppError('No access token', 401);
+    }
+
+    req.user = verifyToken(header.split(' ')[1], env.ACCESS_TOKEN_SECRET, 'Invalid or expired access token');
+    next();
+};
+
+export default authenticate;

package/template/middlewares/errorMiddleware.js

@@ -0,0 +1,33 @@
+import AppError from '../utils/AppError.js';
+
+export const notFound = (req, res, next) => {
+    next(new AppError(`Route not found: ${req.method} ${req.originalUrl}`, 404));
+};
+
+export const errorHandler = (err, req, res, next) => {
+    let error = err;
+
+    if (err.type === 'entity.parse.failed') {
+        error = new AppError('Invalid JSON body', 400);
+    }
+
+    if (err.code === '23505') {
+        const field = err.detail?.match(/Key \((.+?)\)/)?.[1] ?? 'value';
+        error = new AppError(`${field} already exists`, 409);
+    }
+
+    if (err.code === '22P02') {
+        error = new AppError('Invalid input value', 400);
+    }
+
+    const statusCode = error instanceof AppError ? error.statusCode : 500;
+
+    if (statusCode === 500) {
+        console.error(err);
+    }
+
+    res.status(statusCode).json({
+        message: statusCode === 500 ? 'Internal server error' : error.message,
+        ...(error.details && { errors: error.details }),
+    });
+};

package/template/middlewares/rateLimitMiddleware.js

@@ -0,0 +1,14 @@
+import rateLimit from 'express-rate-limit';
+import env from '../config/env.js';
+import AppError from '../utils/AppError.js';
+
+export const apiLimiter = rateLimit({
+    windowMs: 15 * 60 * 1000,
+    limit: 100,
+    standardHeaders: 'draft-8',
+    legacyHeaders: false,
+    skip: () => env.NODE_ENV === 'test',
+    handler: (req, res, next) => {
+        next(new AppError('Too many requests, please try again in 15 minutes', 429));
+    },
+});

package/template/middlewares/roleMiddleware.js

@@ -0,0 +1,22 @@
+import { PERMISSIONS } from '../config/permissions.js';
+import AppError from '../utils/AppError.js';
+
+export const authorize = (permission) => {
+    return (req, res, next) => {
+        if (!req.user?.role) {
+            return next(new AppError('Not authenticated', 401));
+        }
+
+        const allowedRoles = PERMISSIONS[permission];
+
+        if (!allowedRoles) {
+            return next(new AppError('Permission not defined', 403));
+        }
+
+        if (!allowedRoles.includes(req.user.role)) {
+            return next(new AppError('Access denied', 403));
+        }
+
+        next();
+    };
+};

package/template/middlewares/validateMiddleware.js

@@ -0,0 +1,18 @@
+import AppError from '../utils/AppError.js';
+
+export const validate = (schema, source = 'body') => {
+    return (req, res, next) => {
+        const result = schema.safeParse(req[source] ?? {});
+
+        if (!result.success) {
+            const errors = result.error.issues.map((issue) => ({
+                field: issue.path.join('.'),
+                message: issue.message,
+            }));
+            return next(new AppError('Validation failed', 400, errors));
+        }
+
+        req[source] = result.data;
+        next();
+    };
+};

package/template/migrations/1792673478177_create-users-table.sql

@@ -0,0 +1,16 @@
+-- Up Migration
+CREATE TYPE user_role AS ENUM ('user', 'admin');
+
+CREATE TABLE users (
+  id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  email VARCHAR(255) NOT NULL UNIQUE,
+  password VARCHAR(255) NOT NULL,
+  refresh_token CHAR(64),
+  role user_role NOT NULL DEFAULT 'user',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Down Migration
+DROP TABLE users;
+DROP TYPE user_role;

package/template/migrations/1792842956065_create-refresh-tokens-table.sql

@@ -0,0 +1,17 @@
+-- Up Migration
+CREATE TABLE refresh_tokens (
+  id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  user_id INT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash CHAR(64) NOT NULL UNIQUE,
+  expires_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX refresh_tokens_user_id_idx ON refresh_tokens (user_id);
+
+ALTER TABLE users DROP COLUMN refresh_token;
+
+-- Down Migration
+ALTER TABLE users ADD COLUMN refresh_token CHAR(64);
+
+DROP TABLE refresh_tokens;

package/template/migrations/1792842957555_create-products-table.sql

@@ -0,0 +1,14 @@
+-- Up Migration
+CREATE TABLE products (
+  id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  description TEXT,
+  price NUMERIC(10, 2) NOT NULL CHECK (price >= 0),
+  stock INT NOT NULL DEFAULT 0 CHECK (stock >= 0),
+  image_url TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Down Migration
+DROP TABLE products;

package/template/models/productModel.js

@@ -0,0 +1,42 @@
+import db from '../config/db.js';
+
+const getAll = async () => {
+    const { rows } = await db.query('SELECT * FROM products ORDER BY id');
+    return rows;
+};
+
+const findById = async (id) => {
+    const { rows } = await db.query('SELECT * FROM products WHERE id = $1', [id]);
+    return rows[0];
+};
+
+const create = async ({ name, description = null, price, stock = 0, image_url = null }) => {
+    const { rows } = await db.query(
+        'INSERT INTO products (name, description, price, stock, image_url) VALUES ($1, $2, $3, $4, $5) RETURNING *',
+        [name, description, price, stock, image_url]
+    );
+    return rows[0];
+};
+
+const update = async (id, fields) => {
+    const columns = Object.keys(fields);
+    const setClause = columns.map((column, index) => `${column} = $${index + 1}`).join(', ');
+    const { rows } = await db.query(
+        `UPDATE products SET ${setClause}, updated_at = now() WHERE id = $${columns.length + 1} RETURNING *`,
+        [...Object.values(fields), id]
+    );
+    return rows[0];
+};
+
+const remove = async (id) => {
+    const { rowCount } = await db.query('DELETE FROM products WHERE id = $1', [id]);
+    return rowCount > 0;
+};
+
+export default {
+    getAll,
+    findById,
+    create,
+    update,
+    remove
+};

package/template/models/refreshTokenModel.js

@@ -0,0 +1,25 @@
+import db from '../config/db.js';
+
+const create = async (userId, tokenHash, expiresAt) => {
+    await db.query('INSERT INTO refresh_tokens (user_id, token_hash, expires_at) VALUES ($1, $2, $3)', [userId, tokenHash, expiresAt]);
+};
+
+const findByHash = async (tokenHash) => {
+    const { rows } = await db.query('SELECT * FROM refresh_tokens WHERE token_hash = $1 AND expires_at > now()', [tokenHash]);
+    return rows[0];
+};
+
+const deleteByHash = async (tokenHash) => {
+    await db.query('DELETE FROM refresh_tokens WHERE token_hash = $1', [tokenHash]);
+};
+
+const deleteAllForUser = async (userId) => {
+    await db.query('DELETE FROM refresh_tokens WHERE user_id = $1', [userId]);
+};
+
+export default {
+    create,
+    findByHash,
+    deleteByHash,
+    deleteAllForUser
+};

package/template/models/userModel.js

@@ -0,0 +1,39 @@
+import db from '../config/db.js';
+import bcrypt from 'bcrypt';
+
+const PUBLIC_COLUMNS = 'id, name, email, role, created_at';
+
+const getAllUsers = async () => {
+    const { rows } = await db.query(`SELECT ${PUBLIC_COLUMNS} FROM users`);
+    return rows;
+};
+
+const findOne = async (email) => {
+    const { rows } = await db.query('SELECT * FROM users WHERE email = $1', [email]);
+    return rows[0];
+}
+
+const findById = async (id) => {
+    const { rows } = await db.query('SELECT * FROM users WHERE id = $1', [id]);
+    return rows[0];
+};
+
+const findPublicById = async (id) => {
+    const { rows } = await db.query(`SELECT ${PUBLIC_COLUMNS} FROM users WHERE id = $1`, [id]);
+    return rows[0];
+};
+
+const createUser = async (userData) => {
+    const { name, email, password, role = 'user' } = userData;
+    const hashedPassword = await bcrypt.hash(password, 10);
+    const { rows } = await db.query('INSERT INTO users (name, email, password, role) VALUES ($1, $2, $3, $4) RETURNING id', [name, email, hashedPassword, role]);
+    return rows[0].id;
+};
+
+export default {
+    getAllUsers,
+    createUser,
+    findOne,
+    findById,
+    findPublicById
+};

package/template/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "simo-api",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "migrate": "node-pg-migrate -j sql",
+    "migrate:up": "node-pg-migrate up -j sql",
+    "migrate:down": "node-pg-migrate down -j sql",
+    "start": "node index.js",
+    "dev": "nodemon index.js",
+    "test": "NODE_ENV=test node --test 'tests/**/*.test.js'",
+    "seed": "node seeds/seed.js"
+  },
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "dotenv": "^18.0.8",
+    "express": "^5.3.0",
+    "express-rate-limit": "^8.7.1",
+    "jsonwebtoken": "^9.0.3",
+    "morgan": "^1.12.1",
+    "pg": "^8.23.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "node-pg-migrate": "^9.0.0",
+    "nodemon": "^3.1.14",
+    "supertest": "^7.3.1"
+  },
+  "private": true
+}

package/template/routes/authRoutes.js

@@ -0,0 +1,13 @@
+import express from 'express';
+const router = express.Router();
+
+import authController from '../controllers/authController.js';
+import { validate } from '../middlewares/validateMiddleware.js';
+import { loginSchema, registerSchema } from '../validations/authValidation.js';
+
+router.post('/login', validate(loginSchema), authController.login);
+router.post('/register', validate(registerSchema), authController.register);
+router.post('/refresh', authController.refresh, authController.clearRefreshCookieOnError);
+router.post('/logout', authController.logout);
+
+export default router;

package/template/routes/index.js

@@ -0,0 +1,15 @@
+import express from 'express';
+const router = express.Router();
+
+import authRoutes from './authRoutes.js';
+import userRoutes from './userRoutes.js';
+import productRoutes from './productRoutes.js';
+
+
+
+router.use('/auth', authRoutes);
+router.use('/user', userRoutes);
+router.use('/product', productRoutes);
+
+
+export default router;

package/template/routes/productRoutes.js

@@ -0,0 +1,17 @@
+import express from 'express';
+const router = express.Router();
+
+import productController from '../controllers/productController.js';
+import authenticate from '../middlewares/authMiddleware.js';
+import { authorize } from '../middlewares/roleMiddleware.js';
+import { validate } from '../middlewares/validateMiddleware.js';
+import { createProductSchema, updateProductSchema, productIdSchema } from '../validations/productValidation.js';
+
+
+router.get('/getAll', productController.getAllProducts);
+router.get('/:id', validate(productIdSchema, 'params'), productController.getProductById);
+router.post('/create', authenticate, authorize('PRODUCT_CREATE'), validate(createProductSchema), productController.createProduct);
+router.patch('/update/:id', authenticate, authorize('PRODUCT_UPDATE'), validate(productIdSchema, 'params'), validate(updateProductSchema), productController.updateProduct);
+router.delete('/delete/:id', authenticate, authorize('PRODUCT_DELETE'), validate(productIdSchema, 'params'), productController.deleteProduct);
+
+export default router;

package/template/routes/userRoutes.js

@@ -0,0 +1,15 @@
+import express from 'express';
+const router = express.Router();
+
+import userController from '../controllers/userController.js';
+import authenticate from '../middlewares/authMiddleware.js';
+import { authorize } from '../middlewares/roleMiddleware.js';
+import { validate } from '../middlewares/validateMiddleware.js';
+import { createUserSchema } from '../validations/userValidation.js';
+
+
+router.get('/me', authenticate, userController.getMe);
+router.get('/getAll', authenticate, authorize('USER_GETALL'), userController.getAllUsers);
+router.post('/create', authenticate, authorize('USER_CREATE'), validate(createUserSchema), userController.createUser);
+
+export default router;

package/template/seeds/seed.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import db from '../config/db.js';
+import userModel from '../models/userModel.js';
+import { ROLES } from '../config/permissions.js';
+import { name, email, password } from '../validations/authValidation.js';
+
+const adminSchema = z.object({
+    ADMIN_NAME: name,
+    ADMIN_EMAIL: email,
+    ADMIN_PASSWORD: password,
+});
+
+const seedAdmin = async () => {
+    const result = adminSchema.safeParse(process.env);
+
+    if (!result.success) {
+        console.error('Invalid admin variables in .env:');
+        for (const issue of result.error.issues) {
+            console.error(`  - ${issue.path.join('.')}: ${issue.message}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+
+    const { ADMIN_NAME, ADMIN_EMAIL, ADMIN_PASSWORD } = result.data;
+
+    const existing = await userModel.findOne(ADMIN_EMAIL);
+    if (existing) {
+        console.log(`Admin already exists: ${ADMIN_EMAIL}`);
+        return;
+    }
+
+    const id = await userModel.createUser({
+        name: ADMIN_NAME,
+        email: ADMIN_EMAIL,
+        password: ADMIN_PASSWORD,
+        role: ROLES.ADMIN,
+    });
+
+    console.log(`Admin created: ${ADMIN_EMAIL} (id ${id})`);
+};
+
+try {
+    await seedAdmin();
+} catch (error) {
+    console.error('Seed failed:', error);
+    process.exitCode = 1;
+} finally {
+    await db.end();
+}

package/template/services/authService.js

@@ -0,0 +1,94 @@
+import bcrypt from 'bcrypt';
+import jwt from 'jsonwebtoken';
+import crypto from 'crypto';
+import env from '../config/env.js';
+import { ROLES } from '../config/permissions.js';
+import userModel from '../models/userModel.js';
+import refreshTokenModel from '../models/refreshTokenModel.js';
+import AppError from '../utils/AppError.js';
+import verifyToken from '../utils/verifyToken.js';
+
+export const REFRESH_TOKEN_MAX_AGE = env.REFRESH_TOKEN_EXPIRES_DAYS * 24 * 60 * 60 * 1000;
+
+const hashToken = (token) => crypto.createHash('sha256').update(token).digest('hex');
+
+const generateAccessToken = (user) => {
+    const payload = { id: user.id, email: user.email, role: user.role };
+    return jwt.sign(payload, env.ACCESS_TOKEN_SECRET, { expiresIn: env.ACCESS_TOKEN_EXPIRES_IN });
+};
+
+const generateRefreshToken = (user) => {
+    const payload = { id: user.id, jti: crypto.randomUUID() };
+    return jwt.sign(payload, env.REFRESH_TOKEN_SECRET, { expiresIn: REFRESH_TOKEN_MAX_AGE / 1000 });
+};
+
+const createSession = async (user) => {
+    const accessToken = generateAccessToken(user);
+    const refreshToken = generateRefreshToken(user);
+    const expiresAt = new Date(Date.now() + REFRESH_TOKEN_MAX_AGE);
+
+    await refreshTokenModel.create(user.id, hashToken(refreshToken), expiresAt);
+
+    return { accessToken, refreshToken };
+};
+
+const login = async (email, password) => {
+    const user = await userModel.findOne(email);
+
+    if (!user || !(await bcrypt.compare(password, user.password))) {
+        throw new AppError('Invalid email or password', 401);
+    }
+
+    const tokens = await createSession(user);
+
+    return {
+        ...tokens,
+        user: { id: user.id, name: user.name, email: user.email, role: user.role },
+    };
+};
+
+const register = async ({ name, email, password }) => {
+    const existingUser = await userModel.findOne(email);
+
+    if (existingUser) {
+        throw new AppError('Email already exists', 409);
+    }
+
+    return userModel.createUser({ name, email, password, role: ROLES.USER });
+};
+
+const refresh = async (token) => {
+    if (!token) {
+        throw new AppError('No refresh token', 401);
+    }
+
+    const payload = verifyToken(token, env.REFRESH_TOKEN_SECRET, 'Invalid or expired refresh token');
+
+    const storedToken = await refreshTokenModel.findByHash(hashToken(token));
+    if (!storedToken || storedToken.user_id !== payload.id) {
+        await refreshTokenModel.deleteAllForUser(payload.id);
+        throw new AppError('Refresh token revoked', 401);
+    }
+
+    const user = await userModel.findById(payload.id);
+    if (!user) {
+        throw new AppError('User no longer exists', 401);
+    }
+
+    await refreshTokenModel.deleteByHash(hashToken(token));
+
+    return createSession(user);
+};
+
+const logout = async (token) => {
+    if (token) {
+        await refreshTokenModel.deleteByHash(hashToken(token));
+    }
+};
+
+export default {
+    login,
+    register,
+    refresh,
+    logout
+};

package/template/services/productService.js

@@ -0,0 +1,37 @@
+import productModel from '../models/productModel.js';
+import AppError from '../utils/AppError.js';
+
+const getAll = () => productModel.getAll();
+
+const getById = async (id) => {
+    const product = await productModel.findById(id);
+    if (!product) {
+        throw new AppError('Product not found', 404);
+    }
+    return product;
+};
+
+const create = (data) => productModel.create(data);
+
+const update = async (id, data) => {
+    const product = await productModel.update(id, data);
+    if (!product) {
+        throw new AppError('Product not found', 404);
+    }
+    return product;
+};
+
+const remove = async (id) => {
+    const deleted = await productModel.remove(id);
+    if (!deleted) {
+        throw new AppError('Product not found', 404);
+    }
+};
+
+export default {
+    getAll,
+    getById,
+    create,
+    update,
+    remove
+};

package/template/services/userService.js

@@ -0,0 +1,24 @@
+import { ROLES } from '../config/permissions.js';
+import userModel from '../models/userModel.js';
+import AppError from '../utils/AppError.js';
+
+const getAll = () => userModel.getAllUsers();
+
+const getById = async (id) => {
+    const user = await userModel.findPublicById(id);
+    if (!user) {
+        throw new AppError('User not found', 404);
+    }
+    return user;
+};
+
+const create = ({ name, email, password, role }, currentUser) => {
+    const finalRole = currentUser.role === ROLES.ADMIN ? role : ROLES.USER;
+    return userModel.createUser({ name, email, password, role: finalRole });
+};
+
+export default {
+    getAll,
+    getById,
+    create
+};

package/template/tests/api.test.js

@@ -0,0 +1,174 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import request from 'supertest';
+import app from '../app.js';
+import db from '../config/db.js';
+
+const stamp = Date.now();
+const userEmail = `test.user.${stamp}@test.com`;
+const adminEmail = `test.admin.${stamp}@test.com`;
+const password = 'secret123';
+
+let userToken;
+let adminToken;
+let productId;
+
+const login = (email) => request(app).post('/api/auth/login').send({ email, password });
+
+const refreshCookie = (res) => res.headers['set-cookie'].find((cookie) => cookie.startsWith('refreshToken=')).split(';')[0];
+
+before(async () => {
+    await request(app).post('/api/auth/register').send({ name: 'Test User', email: userEmail, password });
+    await request(app).post('/api/auth/register').send({ name: 'Test Admin', email: adminEmail, password });
+    await db.query("UPDATE users SET role = 'admin' WHERE email = $1", [adminEmail]);
+
+    userToken = (await login(userEmail)).body.accessToken;
+    adminToken = (await login(adminEmail)).body.accessToken;
+});
+
+after(async () => {
+    await db.query('DELETE FROM users WHERE email LIKE $1', [`test.%.${stamp}@test.com`]);
+    if (productId) await db.query('DELETE FROM products WHERE id = $1', [productId]);
+    await db.end();
+});
+
+describe('Auth', () => {
+    it('register returns userId', async () => {
+        const email = `test.register.${stamp}@test.com`;
+        const res = await request(app).post('/api/auth/register').send({ name: 'Reg', email, password });
+        assert.equal(res.status, 201);
+        assert.equal(typeof res.body.userId, 'number');
+    });
+
+    it('register rejects invalid body', async () => {
+        const res = await request(app).post('/api/auth/register').send({ email: 'abc', password: '1' });
+        assert.equal(res.status, 400);
+        assert.deepEqual(res.body.errors.map((e) => e.field).sort(), ['email', 'name', 'password']);
+    });
+
+    it('register rejects existing email (case insensitive)', async () => {
+        const res = await request(app).post('/api/auth/register').send({ name: 'Dup', email: userEmail.toUpperCase(), password });
+        assert.equal(res.status, 409);
+    });
+
+    it('login rejects wrong password', async () => {
+        const res = await request(app).post('/api/auth/login').send({ email: userEmail, password: 'wrong-pass' });
+        assert.equal(res.status, 401);
+    });
+
+    it('login returns access token and refresh cookie', async () => {
+        const res = await login(userEmail);
+        assert.equal(res.status, 200);
+        assert.ok(res.body.accessToken);
+        assert.ok(refreshCookie(res));
+    });
+
+    it('refresh rotates the token and detects reuse', async () => {
+        const oldCookie = refreshCookie(await login(userEmail));
+
+        const first = await request(app).post('/api/auth/refresh').set('Cookie', oldCookie);
+        assert.equal(first.status, 200);
+        const newCookie = refreshCookie(first);
+
+        const reused = await request(app).post('/api/auth/refresh').set('Cookie', oldCookie);
+        assert.equal(reused.status, 401);
+
+        const afterReuse = await request(app).post('/api/auth/refresh').set('Cookie', newCookie);
+        assert.equal(afterReuse.status, 401);
+    });
+
+    it('keeps sessions on two devices', async () => {
+        const deviceA = refreshCookie(await login(userEmail));
+        const deviceB = refreshCookie(await login(userEmail));
+
+        assert.equal((await request(app).post('/api/auth/refresh').set('Cookie', deviceA)).status, 200);
+        assert.equal((await request(app).post('/api/auth/refresh').set('Cookie', deviceB)).status, 200);
+    });
+
+    it('logout revokes the refresh token', async () => {
+        const cookie = refreshCookie(await login(userEmail));
+        assert.equal((await request(app).post('/api/auth/logout').set('Cookie', cookie)).status, 200);
+        assert.equal((await request(app).post('/api/auth/refresh').set('Cookie', cookie)).status, 401);
+    });
+});
+
+describe('Users', () => {
+    it('GET /me returns the connected user without password', async () => {
+        const res = await request(app).get('/api/user/me').set('Authorization', `Bearer ${userToken}`);
+        assert.equal(res.status, 200);
+        assert.equal(res.body.user.email, userEmail);
+        assert.equal(res.body.user.password, undefined);
+    });
+
+    it('GET /me requires a token', async () => {
+        const res = await request(app).get('/api/user/me');
+        assert.equal(res.status, 401);
+    });
+
+    it('getAll is admin only', async () => {
+        const asUser = await request(app).get('/api/user/getAll').set('Authorization', `Bearer ${userToken}`);
+        const asAdmin = await request(app).get('/api/user/getAll').set('Authorization', `Bearer ${adminToken}`);
+        assert.equal(asUser.status, 403);
+        assert.equal(asAdmin.status, 200);
+        assert.ok(asAdmin.body.users.every((user) => user.password === undefined));
+    });
+});
+
+describe('Products', () => {
+    it('user cannot create a product', async () => {
+        const res = await request(app).post('/api/product/create').set('Authorization', `Bearer ${userToken}`).send({ name: 'Nope', price: 10 });
+        assert.equal(res.status, 403);
+    });
+
+    it('rejects invalid product', async () => {
+        const res = await request(app).post('/api/product/create').set('Authorization', `Bearer ${adminToken}`).send({ name: 'X', price: -5 });
+        assert.equal(res.status, 400);
+    });
+
+    it('admin creates a product', async () => {
+        const res = await request(app).post('/api/product/create').set('Authorization', `Bearer ${adminToken}`).send({ name: 'Test Product', price: 99.5, stock: 3 });
+        assert.equal(res.status, 201);
+        productId = res.body.product.id;
+    });
+
+    it('lists and gets products publicly', async () => {
+        const list = await request(app).get('/api/product/getAll');
+        assert.equal(list.status, 200);
+        assert.ok(list.body.products.some((product) => product.id === productId));
+
+        const one = await request(app).get(`/api/product/${productId}`);
+        assert.equal(one.status, 200);
+        assert.equal(one.body.product.name, 'Test Product');
+    });
+
+    it('admin updates a product', async () => {
+        const res = await request(app).patch(`/api/product/update/${productId}`).set('Authorization', `Bearer ${adminToken}`).send({ stock: 10 });
+        assert.equal(res.status, 200);
+        assert.equal(res.body.product.stock, 10);
+    });
+
+    it('rejects update with unknown field', async () => {
+        const res = await request(app).patch(`/api/product/update/${productId}`).set('Authorization', `Bearer ${adminToken}`).send({ hacked: true });
+        assert.equal(res.status, 400);
+    });
+
+    it('returns 400 for invalid id and 404 for missing product', async () => {
+        assert.equal((await request(app).get('/api/product/abc')).status, 400);
+        assert.equal((await request(app).get('/api/product/999999999')).status, 404);
+    });
+
+    it('admin deletes a product', async () => {
+        const res = await request(app).delete(`/api/product/delete/${productId}`).set('Authorization', `Bearer ${adminToken}`);
+        assert.equal(res.status, 200);
+        assert.equal((await request(app).get(`/api/product/${productId}`)).status, 404);
+        productId = null;
+    });
+});
+
+describe('Errors', () => {
+    it('unknown route returns JSON 404', async () => {
+        const res = await request(app).get('/api/does-not-exist');
+        assert.equal(res.status, 404);
+        assert.match(res.body.message, /Route not found/);
+    });
+});

package/template/utils/AppError.js

@@ -0,0 +1,10 @@
+class AppError extends Error {
+    constructor(message, statusCode = 500, details) {
+        super(message);
+        this.name = 'AppError';
+        this.statusCode = statusCode;
+        this.details = details;
+    }
+}
+
+export default AppError;

package/template/utils/verifyToken.js

@@ -0,0 +1,12 @@
+import jwt from 'jsonwebtoken';
+import AppError from './AppError.js';
+
+const verifyToken = (token, secret, message = 'Invalid or expired token') => {
+    try {
+        return jwt.verify(token, secret);
+    } catch {
+        throw new AppError(message, 401);
+    }
+};
+
+export default verifyToken;

package/template/validations/authValidation.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+export const email = z.string().trim().toLowerCase().pipe(z.email());
+
+export const password = z.string().min(6, 'Password must be at least 6 characters').max(72);
+
+export const name = z.string().trim().min(2, 'Name must be at least 2 characters').max(255);
+
+export const registerSchema = z.object({
+    name,
+    email,
+    password,
+});
+
+export const loginSchema = z.object({
+    email,
+    password: z.string().min(1, 'Password is required'),
+});

package/template/validations/productValidation.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+const productFields = {
+    name: z.string().trim().min(2).max(255),
+    description: z.string().trim().max(5000).nullable().optional(),
+    price: z.coerce.number().nonnegative().max(99999999.99),
+    stock: z.coerce.number().int().nonnegative().optional(),
+    image_url: z.url().nullable().optional(),
+};
+
+export const createProductSchema = z.object(productFields);
+
+export const updateProductSchema = z
+    .object(productFields)
+    .partial()
+    .strict()
+    .refine((data) => Object.keys(data).length > 0, { message: 'At least one field is required' });
+
+export const productIdSchema = z.object({
+    id: z.coerce.number().int().positive(),
+});

package/template/validations/userValidation.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { ROLES } from '../config/permissions.js';
+import { name, email, password } from './authValidation.js';
+
+export const createUserSchema = z.object({
+    name,
+    email,
+    password,
+    role: z.enum(Object.values(ROLES)).optional(),
+});