secNotify-BEnd

• About
• Features
• Tech Stack
• Architecture
• Getting Started
• Key Endpoints
• Project Structure
• Configuration
• Roadmap
• Contributing
• License

secNotify-BEnd is the authentication core for the Secure Notify platform. It handles user login, hashes passwords with bcrypt, and creates JSON Web Tokens that are stored in the database for each session. Other services in the platform send their tokens to this backend to be verified, so it acts as a shared source of identity for the wider system.

The service is built on NestJS with TypeORM over PostgreSQL. It models three roles (admin, user, and rider) and uses guards and decorators to protect routes. A faker module is included to seed the database with demo users so the app can be tried end to end without manual data entry.

The package name in package.json is secure-notify-core, which reflects this role as the identity core of the platform.

• Email or username login that returns access and refresh tokens.
• Password hashing with bcrypt and account lockout fields (failed attempts, blocked until).
• Database backed tokens with session tracking; logging in clears other sessions for the same user.
• Token verification endpoints, including a diagnostic endpoint for troubleshooting JWT secrets.
• Role based access control with ADMIN, USER, and RIDER roles via guards and decorators.
• User and rider management scoped by organization (create, read, update, soft delete).
• A faker module to seed the database with demo users.
• Swagger API documentation served at /api.

flowchart LR
    Client[Client App] -->|POST /auth/login| Auth[Auth Module]
    Other[Other Service] -->|POST /auth/verifyToken| Auth
    Auth --> TokenSvc[Token Service]
    Auth --> Users[Users Module]
    TokenSvc --> Repo[Token Repository]
    Users --> DB[(PostgreSQL)]
    Repo --> DB
    Faker[Faker Module] --> DB
    Auth -.->|JWT guard + roles| Guards[Guards and Decorators]

node --version   # Node.js 18 or newer
npm --version
# A running PostgreSQL instance

git clone https://github.com/atiqbitstream/secNotify-BEnd.git
cd secNotify-BEnd
git checkout dec-release
npm install

Create a .local.env file in the project root. The app reads it through @nestjs/config (see src/app.module.ts). See Configuration for the variables.

npm run start:dev     # watch mode
npm run start         # standard
npm run build         # compile to dist/
npm run start:prod    # run the compiled build

The service listens on port 3000. Swagger UI is available at http://localhost:3000/api.

npm run test          # unit tests
npm run test:e2e      # end to end tests
npm run test:cov      # coverage

src/
  app.module.ts          Root module, TypeORM and config wiring
  main.ts                Bootstrap, CORS, Swagger, port 3000
  auth/                  Login, JWT strategy, guards, decorators, entities
    services/            AuthService (login, validate user)
    guards/              JwtAuthGuard, RolesGuard
    decorators/          @Public, @Roles, @CurrentUser
    entities/            Account, Token, Password2fa
    strategies/          JwtStrategy
  shared/                TokenService and TokenRepository (shared module)
  users/                 User entity, DTOs, controller, service, roles enum
  faker/                 Demo data seeding module
  utils/                 Dates, constants, error messages, reset helpers
test/                    End to end tests

The app loads environment variables from .local.env via @nestjs/config. The variables read in code are:

• Stop committing .local.env; ship a .local.env.example and rotate all secrets.
• Add a refresh token rotation endpoint (the logic is drafted but commented out).
• Restrict CORS to known frontend origins instead of *.
• Re-enable JWT expiration checking in the strategy (ignoreExpiration is currently true).
• Replace synchronize: true with managed migrations for production.
• Add a real Swagger title and description in place of the placeholder text.

Contributions are welcome. Open an issue to discuss a change, then submit a pull request against the active release branch.

Distributed under the MIT License. See LICENSE.