{"id":21978773,"url":"https://github.com/louis3797/express-ts-auth-service","last_synced_at":"2025-04-13T00:46:40.307Z","repository":{"id":261865413,"uuid":"610455697","full_name":"Louis3797/express-ts-auth-service","owner":"Louis3797","description":" A ready-to-use authentication service build with express.js, that provides secure and reliable authentication using JSON Web Tokens (JWT) and refresh token rotation","archived":false,"fork":false,"pushed_at":"2024-11-09T12:28:54.000Z","size":395,"stargazers_count":233,"open_issues_count":7,"forks_count":39,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-13T00:46:32.755Z","etag":null,"topics":["authentication","boilerplate","eslint","express","express-typescript","express-typescript-boilerplate","jest","jwt","jwt-authentication","mysql","node-boilerplate","nodejs","prisma","refresh-token","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Louis3797.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-06T20:08:55.000Z","updated_at":"2025-04-05T20:28:41.000Z","dependencies_parsed_at":"2024-11-08T22:22:08.224Z","dependency_job_id":"5bc79e48-99df-435a-9303-3e3c12bd4e60","html_url":"https://github.com/Louis3797/express-ts-auth-service","commit_stats":null,"previous_names":["louis3797/express-ts-auth-service"],"tags_count":0,"template":true,"template_full_name":"Louis3797/express-ts-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Louis3797%2Fexpress-ts-auth-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Louis3797%2Fexpress-ts-auth-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Louis3797%2Fexpress-ts-auth-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Louis3797%2Fexpress-ts-auth-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Louis3797","download_url":"https://codeload.github.com/Louis3797/express-ts-auth-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650434,"owners_count":21139672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","boilerplate","eslint","express","express-typescript","express-typescript-boilerplate","jest","jwt","jwt-authentication","mysql","node-boilerplate","nodejs","prisma","refresh-token","typescript"],"created_at":"2024-11-29T16:26:35.371Z","updated_at":"2025-04-13T00:46:40.287Z","avatar_url":"https://github.com/Louis3797.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nHey, thanks for using the awesome-readme-template template.\nIf you have any enhancements, then fork this project and create a pull request\nor just open an issue with the label \"enhancement\".\n\nDon't forget to give this project a star for additional support ;)\nMaybe you can mention me or this repo in the acknowledgements too\n--\u003e\n\u003cdiv align=\"center\"\u003e\n\n  \u003ch1\u003eExpress-Ts-Auth-Service\u003c/h1\u003e\n  \n  \u003cp\u003e\nA pre-built authentication server that uses JSON Web Tokens (JWT) for authentication. It is built using Express.js, TypeScript and MySQL\n  \u003c/p\u003e\n  \n\u003c!-- Badges --\u003e\n\u003cp\u003e\n  \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/graphs/contributors\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/contributors/Louis3797/express-ts-auth-service\" alt=\"contributors\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/last-commit/Louis3797/express-ts-auth-service\" alt=\"last update\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/network/members\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/forks/Louis3797/express-ts-auth-service\" alt=\"forks\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/Louis3797/express-ts-auth-service\" alt=\"stars\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/issues/\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues/Louis3797/express-ts-auth-service\" alt=\"open issues\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/Louis3797/express-ts-auth-service.svg\" alt=\"license\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch4\u003e\n    \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service#readme\"\u003eDocumentation\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n    \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/issues/\"\u003eReport Bug\u003c/a\u003e\n  \u003cspan\u003e · \u003c/span\u003e\n    \u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/issues/\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/h4\u003e\n\u003c/div\u003e\n\n\u003c!-- Table of Contents --\u003e\n\n# Table of Contents\n\n- [Table of Contents](#table-of-contents)\n  - [About the Project](#about-the-project)\n    - [Tech Stack](#tech-stack)\n    - [Features](#features)\n    - [Endpoints](#endpoints)\n    - [Project Structure](#project-structure)\n    - [Database](#database)\n      - [Account](#account)\n      - [User](#user)\n      - [RefreshToken](#refreshtoken)\n      - [ResetToken](#resettoken)\n      - [EmailVerificationToken](#emailverificationtoken)\n    - [Refresh Token Rotation](#refresh-token-rotation)\n    - [Environment Variables](#environment-variables)\n  - [Getting Started](#getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Installation](#installation)\n    - [Linting](#linting)\n    - [Running Tests](#running-tests)\n    - [Run Locally](#run-locally)\n    - [Run with Docker](#run-with-docker)\n  - [Roadmap](#roadmap)\n  - [Contributing](#contributing)\n    - [Code of Conduct](#code-of-conduct)\n  - [License](#license)\n  - [Contact](#contact)\n  - [Acknowledgements](#acknowledgements)\n\n\u003c!-- About the Project --\u003e\n\n## About the Project\n\nThis pre-built authentication server is designed to simplify the process of adding secure user authentication to your web or mobile application. It provides a ready-made solution that uses JSON Web Tokens (JWT) to ensure reliable and secure user sessions, saving you time and resources that would otherwise be required to develop an authentication system from scratch. Built using Express.js and TypeScript, this server is also highly customizable and can be extended to meet the specific needs of your application. By integrating our authentication server into your application, you can rest assured that your users' data and sessions are well protected, leaving you free to focus on other important aspects of your application.\n\n\u003c!-- TechStack --\u003e\n\n### Tech Stack\n\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"https://skillicons.dev\"\u003e\n    \u003cimg src=\"https://skillicons.dev/icons?i=ts,nodejs,express,mysql,docker,prisma\u0026perline=13\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- Features --\u003e\n\n### Features\n\n- :black_nib: Written in TypeScript for type-safe code\n- :floppy_disk: Utilize a MySQL database to efficiently store user data\n- :speaking_head: Interacts with the database using the powerful Prisma ORM\n- :lock: Implements secure authentication measures with JWTs, ensuring secure access to sensitive data\n- :key: Implements robust password hashing using Argon2 for maximum security\n- :recycle: Incorporates refresh token rotation functionality to enhance the security\n- :white_check_mark: Includes email verification functionality for new user sign-ups\n- :new: Provides a reset password function for users who have forgotten their password\n- :rabbit2: Enables faster data transfer by implementing GZIP compression\n- :policeman: Implements essential security features using Helmet middleware\n- :cookie: Parses cookies seamlessly with cookie-parser middleware\n- :gear: Allows cross-origin resource sharing using CORS\n- :soap: Sanitizes request data against cross-site-scripting with xss middleware\n- :capital_abcd: Manages environment variables with ease using dotenv\n- :male_detective: Enforces high code quality standards with ESLint and Prettier\n- :horse_racing: Implements rate limiting to prevent abuse and improve server performance\n- :information_source: Accurately manages HTTP response status codes using http-status library\n- :warning: Validates user input with the powerful and flexible Joi library\n- :email: Facilitates sending of emails using nodemailer library\n- :memo: Enables detailed logging of server activities using winston library\n- :dog: Implements Git hooks with Husky to optimize development processes\n- :test_tube: Ensure reliability and robustness of the application with thorough testing using Jest and Supertest\n\n\u003c!-- Endpoints --\u003e\n\n### Endpoints\n\n```\nPOST /v1/auth/signup - Signup\nPOST /v1/auth/login - Login\nPOST /v1/auth/refresh - Refresh access token\nPOST /v1/forgot-password - Send reset password email\nPOST /v1/reset-password/:token - Reset password\nPOST /v1/send-verification-email - Send verification email\nPOST /v1/verify-email/:token - Verify email\n```\n\n\u003c!-- Project Structure --\u003e\n\n### Project Structure\n\n```\n./src\n├── config/         # Config files\n├── controller/     # Route controllers\n├── middleware/     # Custom middlewares\n├── routes/         # Routes\n├── types/          # Types\n├── utils/          # Utility classes and functions\n├── validations/    # Validation schemas\n├── app.ts          # Express App\n└── index.ts        # App Entrypoint\n```\n\n\u003c!-- Database --\u003e\n\n### Database\n\nOur server relies on MySQL as its primary database management system to store and manage all relevant data. MySQL is a popular and widely used open-source relational database system that provides efficient, secure, and scalable storage and retrieval of data.\n\nTo simplify and streamline the process of managing the data stored in the MySQL database, we utilize Prisma, which is a modern, type-safe ORM that supports various databases, including MySQL.\n\nPrisma helps us to write database queries in a more readable and intuitive way, making it easier to manage the data stored in our MySQL database. By using Prisma as our ORM of choice, we can also ensure that our application remains scalable, efficient, and maintainable.\n\nIf you're interested in the structure of our database, you can take a look at the data model presented below, which provides an overview of the tables, columns, and relationships within the database.\n\n```js\n\nmodel Account {\n  id                String   @id @default(cuid())\n  userId            String\n  type              String\n  provider          String\n  providerAccountId String\n  refresh_token     String?  @db.Text\n  access_token      String?  @db.Text\n  expiresAt         DateTime\n  token_type        String?\n  scope             String?\n  id_token          String?  @db.Text\n  session_state     String?\n\n  user User @relation(fields: [userId], references: [id], onDelete: Cascade)\n\n  @@unique([provider, providerAccountId])\n}\n\nmodel User {\n  id                     String                   @id @default(cuid())\n  name                   String\n  email                  String?                  @unique\n  password               String\n  emailVerified          DateTime?\n  createdAt              DateTime                 @default(now())\n  accounts               Account[]\n  refreshTokens          RefreshToken[]\n  resetToken             ResetToken[]\n  emailVerificationToken EmailVerificationToken[]\n}\n\nmodel RefreshToken {\n  id        String   @id @default(cuid())\n  token     String   @unique\n  user      User     @relation(fields: [userId], references: [id])\n  userId    String\n  createdAt DateTime @default(now())\n}\n\nmodel ResetToken {\n  id        String   @id @default(cuid())\n  token     String   @unique\n  expiresAt DateTime\n  user      User     @relation(fields: [userId], references: [id])\n  userId    String\n  createdAt DateTime @default(now())\n}\n\nmodel EmailVerificationToken {\n  id        String   @id @default(cuid())\n  token     String   @unique\n  expiresAt DateTime\n  user      User     @relation(fields: [userId], references: [id])\n  userId    String\n  createdAt DateTime @default(now())\n}\n```\n\n#### Account\n\n\u003e Social auth is not yet implemented so that the entity can be different in the future\n\nThe Account entity represents a linked social media account for a user. It has the following fields:\n\n- id: A unique identifier for the account.\n- userId: The ID of the user associated with the account.\n- type: The type of account, e.g. oauth.\n- provider: The provider of the account, e.g. facebook.\n- providerAccountId: The ID associated with the account from the provider's perspective.\n- refresh_token: A refresh token used to obtain a new access token.\n- access_token: An access token used to authenticate requests to the provider's API.\n- expiresAt: The expiration time of the access token.\n- token_type: The type of access token.\n- scope: The scope of the access token.\n- id_token: An ID token associated with the account.\n- session_state: The session state of the account.\n\n#### User\n\nThe User entity represents a user of the application. It has the following fields:\n\n- id: A unique identifier for the user.\n- name: The name of the user.\n- email: The email address of the user.\n- password: The password of the user.\n- emailVerified: The date and time when the user's email address was verified.\n- createdAt: The date of creation.\n- accounts: A list of linked social media accounts for the user.\n- refreshTokens: A list of refresh tokens associated with the user.\n- resetToken: A list of reset tokens associated with the user.\n- emailVerificationToken: A list of email verification tokens associated with the user.\n\n#### RefreshToken\n\nThe RefreshToken entity represents a refresh token used to obtain a new access token. It has the following fields:\n\n- id: A unique identifier for the refresh token.\n- token: The token itself.\n- user: The user associated with the refresh token.\n- userId: The ID of the user associated with the refresh token.\n- createdAt: The date of creation.\n\n#### ResetToken\n\nThe ResetToken entity represents a reset token used to reset a user's password. It has the following fields:\n\n- id: A unique identifier for the refresh token.\n- token: The token itself.\n- expiresAt: The expiration time of the reset token.\n- user: The user associated with the reset token.\n- userId: The ID of the user associated with the reset token.\n- createdAt: The date of creation.\n\n#### EmailVerificationToken\n\nThe EmailVerificationToken entity represents a token used to verify a user's email address. It has the following fields:\n\n- id: A unique identifier for the refresh token.\n- token: The token itself.\n- expiresAt: The expiration time of the email verification token.\n- user: The user associated with the email verification token.\n- userId: The ID of the user associated with the email verification token.\n- createdAt: The date of creation.\n\n\u003c!-- Refresh Token Rotation --\u003e\n\n### Refresh Token Rotation\n\nRefresh token rotation is a security practice used to mitigate the risk of unauthorized access to a user's account or resources. When a user logs in to an application, the application issues an access token and a refresh token. The access token is used to access the user's resources, while the refresh token is used to obtain a new access token when the current one expires.\n\nIn refresh token rotation, the application periodically rotates the refresh token, meaning it invalidates the old refresh token and issues a new one. This practice can limit the amount of time an attacker can use a stolen refresh token to gain access to the user's account or resources. By rotating the refresh token, the application reduces the risk of a long-lived refresh token being used to access the user's account or resources without their permission.\n\n![Refresh Token Rotation Flow](https://github.com/Louis3797/express-ts-auth-service/blob/main/assets/refresh_token_rotation_flow_diagram.png)\n\n\u003c!-- Env Variables --\u003e\n\n### Environment Variables\n\nTo run this project, you will need to add the following environment variables to your .env file\n\n```\n# App's running environment\nNODE_ENV=\n\n# App's running port\nPORT=\n\n# Server url\nSERVER_URL=\n\n# Cors origin url\nCORS_ORIGIN=\n\n# Run node -e \"console.log(require('crypto').randomBytes(256).toString('base64'));\" in your console to generate a secret\nACCESS_TOKEN_SECRET=\n\nREFRESH_TOKEN_SECRET=\n\nACCESS_TOKEN_EXPIRE=\n\nREFRESH_TOKEN_EXPIRE=\n\n# name of the refresh token cookie\nREFRESH_TOKEN_COOKIE_NAME=\n\nMYSQL_DATABASE=\nMYSQL_ROOT_PASSWORD=\n\n# Example: mysql://USER:PASSWORD@HOST:PORT/DATABASE\nDATABASE_URL=\n\n# Configuration for the emial service\nSMTP_HOST=\nSMTP_PORT=\nSMTP_USERNAME=\nSMTP_PASSWORD=\nEMAIL_FROM=\n```\n\nSee .env.example for further details\n\n\u003c!-- Getting Started --\u003e\n\n## Getting Started\n\n\u003c!-- Prerequisites --\u003e\n\n### Prerequisites\n\nThis project uses Yarn as package manager\n\n```bash\n npm install --global yarn\n```\n\n\u003c!-- Installation --\u003e\n\n### Installation\n\n```bash\n  git clone https://github.com/Louis3797/express-ts-auth-service.git\n```\n\nGo to the project directory\n\n```bash\n  cd express-ts-auth-service\n```\n\n```bash\n  yarn install\n```\n\n### Linting\n\n```bash\n  # run ESLint\n  yarn lint\n\n  # fix ESLint errors\n  yarn lint:fix\n\n  # run prettier\n  yarn prettier:check\n\n  # fix prettier errors\n  yarn prettier:format\n\n  # fix prettier errors in specific file\n  yarn prettier:format:file \u003cfile-name\u003e\n```\n\n\u003c!-- Running Tests --\u003e\n\n### Running Tests\n\nTo run tests, run the following command\n\n```bash\n  yarn test\n```\n\nRun tests with watch flag\n\n```bash\n  yarn test:watch\n```\n\nSee test coverage\n\n```bash\n  yarn coverage\n```\n\n\u003c!-- Run Locally --\u003e\n\n### Run Locally\n\nStart the server in development mode\n\n\u003e Note: Dont forget to define the .env variables\n\n```bash\n  yarn dev\n```\n\nStart the server in production mode\n\n```bash\n  yarn start\n```\n\n\u003c!-- Run with Docker --\u003e\n\n### Run with Docker\n\nRun docker compose\n\n```bash\n  cd express-ts-auth-service\n  docker-compose up\n```\n\n\u003c!-- Roadmap --\u003e\n## Roadmap\n\n- [ ] Winston + morgan for logging ?\n- [ ] Clean and order imports\n  - [x] Order imports\n  - [ ] Add index.ts files for cleaner imports\n- [x] Add xss attack prevention middleware\n- [ ] Add API Endpoint documentation\n- [ ] Social Auth\n  - [ ] Google\n  - [ ] Github\n  - [ ] Facebook\n  - [ ] Twitter\n- [ ] Better Error handeling\n  - [ ] Custom Error classes like ```AccessTokenNotFoundError```\n- [ ] Integration Tests\n\n\u003c!-- Contributing --\u003e\n## Contributing\n\n\u003ca href=\"https://github.com/Louis3797/express-ts-auth-service/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=Louis3797/express-ts-auth-service\" /\u003e\n\u003c/a\u003e\n\nContributions are always welcome!\n\nSee `CONTRIBUTING.md` for ways to get started.\n\n\u003c!-- Code of Conduct --\u003e\n### Code of Conduct\n\nPlease read the [Code of Conduct](https://github.com/Louis3797/express-ts-auth-service/blob/main/CODE_OF_CONDUCT.md)\n\n\u003c!-- License --\u003e\n\n## License\n\nDistributed under the MIT License. See LICENSE for more information.\n\n\u003c!-- Contact --\u003e\n\n## Contact\n\nLouis-Kaan Ay - louiskaan.ay@gmail.com\n\nProject Link: [https://github.com/Louis3797/express-ts-auth-service](https://github.com/Louis3797/express-ts-auth-service)\n\n\u003c!-- Acknowledgments --\u003e\n\n## Acknowledgements\n\n- [Readme Template](https://github.com/Louis3797/awesome-readme-template)\n- [Node Express Boilerplate](https://github.com/hagopj13/node-express-boilerplate)\n- [Express Ts Boilerplate](https://github.com/Louis3797/express-ts-boilerplate)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flouis3797%2Fexpress-ts-auth-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flouis3797%2Fexpress-ts-auth-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flouis3797%2Fexpress-ts-auth-service/lists"}