Add generic route access control, apply it to users route, and update README.md

Author: hussein-m-kandil

.env.test

@@ -6,4 +6,6 @@ ADMIN_SECRET=admin_secret
 
 SECRET=secret
 
-TOKEN_EXP_PERIOD=3d
+TOKEN_EXP_PERIOD=3d
+
+ALLOWED_ORIGINS=*

README.md

@@ -1,3 +1,90 @@
 # Generic Express Service
 
-A generic Express.js back-end service that supports multiple front-end projects. Includes RESTful API endpoints, authentication/authorization logic, and maybe some scheduled background jobs for database maintenance.
+A generic Express.js back-end service designed to support multiple front-end apps that I am managing to build in parallel with this app. It includes RESTful API endpoints and user authentication and utilizes PostgreSQL for data persistence.
+
+## Features
+
+- RESTful API with various endpoints serving different purposes
+- User management and authentication endpoints
+- Local PostgreSQL integration via Docker Compose
+- TypeScript support with `tsx` for development
+- Environment-based configuration
+- Tested using Vitest and Supertest
+- Ready for integration with front-end applications
+
+## Getting Started
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (tested on v22 but v20 should be fine too)
+- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/)
+
+## Installation
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/hussein-m-kandil/generic-express-service.git
+   cd generic-express-service
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+3. **Set up the environment variables:**
+
+   ```bash
+   cp .env.test .env
+   # Then edit `.env` to fit your local setup
+   ```
+
+4. **Start the PostgreSQL service:**
+
+   ```bash
+   npm run pg:up
+   ```
+
+5. **Push the Prisma schema to the database:**
+
+   ```bash
+   npx prisma db push
+   ```
+
+6. **Start the development server:**
+
+   ```bash
+   npm run dev
+   ```
+
+   The API will be available at `http://localhost:8080`.
+
+## Running all tests
+
+```bash
+npm run test -- --run
+```
+
+## Deployment
+
+Every _push_ or _pull request (PR)_ on main branch, the app will be deployed to production automatically _if it passes all tests and checks performed by [a GitHub action for deployment preparation](./.github/workflows/deployment-prep.yml)_.
+
+## Notes
+
+- This service is intended to support multiple front-end projects that I build.
+- CORS is configured to allow only specific front-end origins under my control.
+- JWT-based authentication is implemented and required by some endpoint.
+- The `Bearer` schema is included in the authentication response, so _send your token as it is_ via an `Authorization` header.
+- All error responses has the proper status code, but not all of them has a body. If an error response has a body it will have _at least_ the following:
+
+  ```json
+  {
+    "error": {
+      "message": "An example error"
+    }
+  }
+  ```
+
+- A validation error response body will have the form of _[ZodError.issues](https://zod.dev/?id=error-handling)._

requests.rest

@@ -1,9 +1,48 @@
+# Admin token
 GET http://127.0.0.1:8080/api/v1/users
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkzZWE2NjE5LTIyMWEtNDkwYi1iYjcwLWZmZWM0NWQ5MjAyNSIsInVzZXJuYW1lIjoiYWRtaW4iLCJmdWxsbmFtZSI6IkFkbWluIiwiaWF0IjoxNzQ2NDQ2MDA5LCJleHAiOjE3NDY3MDUyMDl9.kIMRW1ctklvIDJf8p_TEMAODHcn3D8HBC6lAkAFDVMs
 
 ###
-GET http://127.0.0.1:8080/api/v1/users/7d517973-7b72-4306-8118-c54021db0585
+
+# Normal user token
+GET http://127.0.0.1:8080/api/v1/users
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+
+###
+
+# Admin token
+GET http://127.0.0.1:8080/api/v1/users/6c655d20-e27d-42b1-a93d-a2a4150876bf
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkzZWE2NjE5LTIyMWEtNDkwYi1iYjcwLWZmZWM0NWQ5MjAyNSIsInVzZXJuYW1lIjoiYWRtaW4iLCJmdWxsbmFtZSI6IkFkbWluIiwiaWF0IjoxNzQ2NDQ2MDA5LCJleHAiOjE3NDY3MDUyMDl9.kIMRW1ctklvIDJf8p_TEMAODHcn3D8HBC6lAkAFDVMs
 
 ###
+
+# Another normal user token
+GET http://127.0.0.1:8080/api/v1/users/93ea6619-221a-490b-bb70-ffec45d92025
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+
+###
+
+# Same user token
+GET http://127.0.0.1:8080/api/v1/users/6c655d20-e27d-42b1-a93d-a2a4150876bf
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+
+###
+
+# Admin
+POST http://127.0.0.1:8080/api/v1/users
+Content-Type: application/json
+
+{
+  "username": "admin",
+  "fullname": "Admin",
+  "password": "Aa@12312",
+  "confirm": "Aa@12312",
+  "secret": "seco_seco"
+}
+
+###
+
+# Normal user
 POST http://127.0.0.1:8080/api/v1/users
 Content-Type: application/json
 
@@ -15,15 +54,21 @@ Content-Type: application/json
 }
 
 ###
-PATCH http://127.0.0.1:8080/api/v1/users/7d517973-7b72-4306-8118-c54021db0585
+
+# Admin token
+PATCH http://127.0.0.1:8080/api/v1/users/6c655d20-e27d-42b1-a93d-a2a4150876bf
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkzZWE2NjE5LTIyMWEtNDkwYi1iYjcwLWZmZWM0NWQ5MjAyNSIsInVzZXJuYW1lIjoiYWRtaW4iLCJmdWxsbmFtZSI6IkFkbWluIiwiaWF0IjoxNzQ2NDQ2MDA5LCJleHAiOjE3NDY3MDUyMDl9.kIMRW1ctklvIDJf8p_TEMAODHcn3D8HBC6lAkAFDVMs
 Content-Type: application/json
 
 {
   "username": "somewhere_man"
 }
 
 ###
-PATCH http://127.0.0.1:8080/api/v1/users/7d517973-7b72-4306-8118-c54021db0585
+
+# Admin token
+PATCH http://127.0.0.1:8080/api/v1/users/6c655d20-e27d-42b1-a93d-a2a4150876bf
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkzZWE2NjE5LTIyMWEtNDkwYi1iYjcwLWZmZWM0NWQ5MjAyNSIsInVzZXJuYW1lIjoiYWRtaW4iLCJmdWxsbmFtZSI6IkFkbWluIiwiaWF0IjoxNzQ2NDQ2MDA5LCJleHAiOjE3NDY3MDUyMDl9.kIMRW1ctklvIDJf8p_TEMAODHcn3D8HBC6lAkAFDVMs
 Content-Type: application/json
 
 {
@@ -32,13 +77,75 @@ Content-Type: application/json
 }
 
 ###
-POST http://127.0.0.1:8080/api/v1/auth/signin
+
+# Same user token
+PATCH http://127.0.0.1:8080/api/v1/users/6c655d20-e27d-42b1-a93d-a2a4150876bf
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+Content-Type: application/json
+
+{
+  "username": "somewhere_man"
+}
+
+###
+
+# Same user token
+PATCH http://127.0.0.1:8080/api/v1/users/6c655d20-e27d-42b1-a93d-a2a4150876bf
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+Content-Type: application/json
+
+{
+  "password": "Sm@12312",
+  "confirm": "Sm@12312"
+}
+
+###
+
+# Another user token
+PATCH http://127.0.0.1:8080/api/v1/users/93ea6619-221a-490b-bb70-ffec45d92025
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
 Content-Type: application/json
 
 {
-  "username": "somewhere_man",
-  "password": "Sm@12312"
+  "username": "somewhere_man"
 }
 
+###
+
+# Another user token
+PATCH http://127.0.0.1:8080/api/v1/users/93ea6619-221a-490b-bb70-ffec45d92025
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+Content-Type: application/json
+
+{
+  "password": "Sm@12312",
+  "confirm": "Sm@12312"
+}
+
+### 
+
+# Admin token
+DELETE http://127.0.0.1:8080/api/v1/users/7d517973-7b72-4306-8118-c54021db0585
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjkzZWE2NjE5LTIyMWEtNDkwYi1iYjcwLWZmZWM0NWQ5MjAyNSIsInVzZXJuYW1lIjoiYWRtaW4iLCJmdWxsbmFtZSI6IkFkbWluIiwiaWF0IjoxNzQ2NDQ2MDA5LCJleHAiOjE3NDY3MDUyMDl9.kIMRW1ctklvIDJf8p_TEMAODHcn3D8HBC6lAkAFDVMs
+
 ### 
-DELETE http://127.0.0.1:8080/api/v1/users/7d517973-7b72-4306-8118-c54021db0585
+
+# Same user token
+DELETE http://127.0.0.1:8080/api/v1/users/6c655d20-e27d-42b1-a93d-a2a4150876bf
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+
+### 
+
+# Another user token
+DELETE http://127.0.0.1:8080/api/v1/users/93ea6619-221a-490b-bb70-ffec45d92025
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjZjNjU1ZDIwLWUyN2QtNDJiMS1hOTNkLWEyYTQxNTA4NzZiZiIsInVzZXJuYW1lIjoibm93aGVyZV9tYW4iLCJmdWxsbmFtZSI6Ik5vd2hlcmUtTWFuIiwiaWF0IjoxNzQ2NDUyMzQ5LCJleHAiOjE3NDY3MTE1NDl9.0lGUkEygKSB5z7RBbKGrP8kY_YeUaoYNISGB9QLWcbc
+
+###
+
+POST http://127.0.0.1:8080/api/v1/auth/signin
+Content-Type: application/json
+
+{
+  "username": "nowhere_man",
+  "password": "Nm@12312"
+}

src/api/v1/auth/auth.router.ts

@@ -8,7 +8,7 @@ import { RequestHandler, Router } from 'express';
 import { AuthResponse } from '../../../types';
 import logger from '../../../lib/logger';
 import passport from '../../../lib/passport';
-import { authValidator } from '../../../middlewares/auth-validator';
+import { authValidator } from '../../../middlewares/validators';
 
 export const authRouter = Router();
 

src/api/v1/users/users.router.ts

@@ -1,8 +1,13 @@
 import { Request, Router } from 'express';
-import { AuthResponse, NewUserInput } from '../../../types';
 import { createJwtForUser } from '../../../lib/helpers';
 import { AppNotFoundError } from '../../../lib/app-error';
+import { AuthResponse, NewUserInput } from '../../../types';
 import { Prisma } from '../../../../prisma/generated/client';
+import {
+  authValidator,
+  adminValidator,
+  createAdminOrOwnerValidator,
+} from '../../../middlewares/validators';
 import userSchema, {
   usernameSchema,
   fullnameSchema,
@@ -13,16 +18,21 @@ import usersService from './users.service';
 
 export const usersRouter = Router();
 
-usersRouter.get('/', async (req, res) => {
+usersRouter.get('/', authValidator, adminValidator, async (req, res) => {
   const users = await usersService.getAll();
   res.json(users);
 });
 
-usersRouter.get('/:id', async (req, res) => {
-  const user = await usersService.findOneById(req.params.id);
-  if (!user) throw new AppNotFoundError('User not found');
-  res.json(user);
-});
+usersRouter.get(
+  '/:id',
+  authValidator,
+  createAdminOrOwnerValidator((req) => req.params.id),
+  async (req, res) => {
+    const user = await usersService.findOneById(req.params.id);
+    if (!user) throw new AppNotFoundError('User not found');
+    res.json(user);
+  }
+);
 
 usersRouter.post('/', async (req, res) => {
   const parsedNewUser = userSchema.parse(req.body);
@@ -36,6 +46,8 @@ usersRouter.post('/', async (req, res) => {
 
 usersRouter.patch(
   '/:id',
+  authValidator,
+  createAdminOrOwnerValidator((req) => req.params.id),
   async (req: Request<{ id: string }, unknown, NewUserInput>, res) => {
     const { username, fullname, password, confirm, secret } = req.body;
     const data: Prisma.UserUpdateInput = {};
@@ -53,9 +65,14 @@ usersRouter.patch(
   }
 );
 
-usersRouter.delete('/:id', async (req, res) => {
-  await usersService.deleteOne(req.params.id);
-  res.status(204).end();
-});
+usersRouter.delete(
+  '/:id',
+  authValidator,
+  createAdminOrOwnerValidator((req) => req.params.id),
+  async (req, res) => {
+    await usersService.deleteOne(req.params.id);
+    res.status(204).end();
+  }
+);
 
 export default usersRouter;