Skip to content

Commit 1ffaf5c

Browse files
khatabwedaakhatabwedaa
committed
Adds initial authentication package for NestJS
Introduces a comprehensive, frontend-agnostic authentication backend package for NestJS applications with support for JWT-based authentication, user registration, password management, email verification, and two-factor authentication. Implements modular feature system allowing selective enablement of authentication capabilities including registration, password reset flows, email verification with signed URLs, profile updates, and TOTP-based 2FA with recovery codes. Provides database-agnostic architecture through repository pattern, supporting any database technology (SQL, NoSQL, etc.) with customizable user creation and password management logic. Includes security features such as configurable rate limiting for login attempts, password confirmation for sensitive actions, and encrypted storage of 2FA secrets and recovery codes. Emits 15 authentication events via @nestjs/event-emitter for integration with application-specific business logic and monitoring systems. Configures development tooling with TypeScript, ESLint, Prettier, Vitest for testing, and pnpm package management.
0 parents  commit 1ffaf5c

75 files changed

Lines changed: 5134 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
github: khatabwedaa

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
node_modules
2+
dist
3+
coverage
4+
*.js.map
5+
*.d.ts.map
6+
.env
7+
*.tsbuildinfo
8+
tasks.*

‎.prettierrc‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"singleQuote": false,
3+
"trailingComma": "all",
4+
"printWidth": 100,
5+
"tabWidth": 2,
6+
"semi": true
7+
}

‎CHANGELOG.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Changelog
2+
3+
All notable changes to `@nestbolt/authentication` will be documented in this file.
4+
5+
## 0.1.0
6+
7+
### Features
8+
9+
- **Initial release** — Frontend-agnostic authentication backend for NestJS
10+
- **Registration** — User registration with customizable creation logic
11+
- **Login/Logout** — JWT-based authentication with access and refresh tokens
12+
- **Password Reset** — Forgot password and reset password flows
13+
- **Email Verification** — Signed URL-based email verification
14+
- **Profile Updates** — Update user profile information
15+
- **Password Updates** — Change password for authenticated users
16+
- **Password Confirmation** — Confirm password for sensitive actions with configurable timeout
17+
- **Two-Factor Authentication** — TOTP-based 2FA with QR code generation
18+
- **Recovery Codes** — 8 recovery codes per user for 2FA backup
19+
- **Feature Flags** — Enable/disable features via module configuration
20+
- **Database Agnostic** — Repository pattern supports any database (SQL, NoSQL, etc.)
21+
- **Events** — 15 authentication events via @nestjs/event-emitter
22+
- **Rate Limiting** — Configurable rate limiting for login and verification

‎CONTRIBUTING.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Contributing to @nestbolt/authentication
2+
3+
Thank you for considering contributing! Here's how you can help.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork:
9+
```bash
10+
git clone https://github.com/<your-username>/authentication.git
11+
cd authentication
12+
```
13+
3. Install dependencies:
14+
```bash
15+
pnpm install
16+
```
17+
4. Create a feature branch:
18+
```bash
19+
git checkout -b my-feature
20+
```
21+
22+
## Development
23+
24+
### Build
25+
26+
```bash
27+
pnpm run build
28+
```
29+
30+
### Run Tests
31+
32+
```bash
33+
pnpm test
34+
```
35+
36+
### Watch Mode
37+
38+
```bash
39+
pnpm test:watch
40+
```
41+
42+
### Lint
43+
44+
```bash
45+
pnpm run lint
46+
```
47+
48+
## Pull Request Guidelines
49+
50+
- Create a feature branch from `main`.
51+
- Keep PRs focused — one feature or fix per PR.
52+
- Make sure all tests pass before submitting.
53+
- Add tests for any new functionality.
54+
- Follow the existing code style and patterns.
55+
56+
## Reporting Issues
57+
58+
- Use [GitHub Issues](https://github.com/nestbolt/authentication/issues) to report bugs or request features.
59+
- For security-related issues, use the **security** label.
60+
61+
## License
62+
63+
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE.md).

‎LICENSE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Nestbolt
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎eslint.config.mjs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import eslint from "@eslint/js";
2+
import tseslint from "typescript-eslint";
3+
import prettierConfig from "eslint-config-prettier";
4+
import prettierPlugin from "eslint-plugin-prettier";
5+
6+
export default tseslint.config(
7+
eslint.configs.recommended,
8+
...tseslint.configs.recommended,
9+
prettierConfig,
10+
{
11+
plugins: {
12+
prettier: prettierPlugin,
13+
},
14+
rules: {
15+
"prettier/prettier": "error",
16+
"@typescript-eslint/no-explicit-any": "off",
17+
"@typescript-eslint/no-non-null-assertion": "warn",
18+
},
19+
},
20+
{
21+
ignores: ["dist/", "node_modules/", "coverage/"],
22+
},
23+
);

‎package.json‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
{
2+
"name": "@nestbolt/authentication",
3+
"version": "0.1.0",
4+
"packageManager": "pnpm@9.15.4",
5+
"description": "Frontend-agnostic authentication backend for NestJS with 2FA, password reset, email verification, and more",
6+
"main": "dist/index.js",
7+
"types": "dist/index.d.ts",
8+
"exports": {
9+
".": {
10+
"types": "./dist/index.d.ts",
11+
"default": "./dist/index.js"
12+
}
13+
},
14+
"files": [
15+
"dist"
16+
],
17+
"scripts": {
18+
"build": "tsc -p tsconfig.build.json",
19+
"test": "vitest run",
20+
"test:watch": "vitest",
21+
"test:cov": "vitest run --coverage",
22+
"test:results": "npx vitest run --coverage 2>&1 | grep -E \"All files|%\" | head -10",
23+
"lint": "eslint 'src/**/*.ts' 'test/**/*.ts'",
24+
"lint:fix": "eslint 'src/**/*.ts' 'test/**/*.ts' --fix",
25+
"format": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
26+
"prepublishOnly": "npm run build"
27+
},
28+
"keywords": [
29+
"nestjs",
30+
"authentication",
31+
"auth",
32+
"jwt",
33+
"passport",
34+
"2fa",
35+
"two-factor",
36+
"totp",
37+
"password-reset",
38+
"email-verification",
39+
"login",
40+
"register"
41+
],
42+
"author": "Nestbolt",
43+
"license": "MIT",
44+
"homepage": "https://github.com/nestbolt/authentication#readme",
45+
"repository": {
46+
"type": "git",
47+
"url": "https://github.com/nestbolt/authentication"
48+
},
49+
"bugs": {
50+
"url": "https://github.com/nestbolt/authentication/issues"
51+
},
52+
"engines": {
53+
"node": ">=20.0.0"
54+
},
55+
"peerDependencies": {
56+
"@nestjs/common": "^10.0.0 || ^11.0.0",
57+
"@nestjs/core": "^10.0.0 || ^11.0.0",
58+
"@nestjs/passport": "^10.0.0 || ^11.0.0",
59+
"@nestjs/jwt": "^10.0.0 || ^11.0.0",
60+
"@nestjs/event-emitter": "^2.0.0 || ^3.0.0",
61+
"@nestjs/throttler": "^5.0.0 || ^6.0.0",
62+
"class-transformer": "^0.5.0",
63+
"class-validator": "^0.14.0",
64+
"reflect-metadata": "^0.1.13 || ^0.2.0",
65+
"passport": "^0.7.0",
66+
"passport-jwt": "^4.0.0",
67+
"passport-local": "^1.0.0"
68+
},
69+
"peerDependenciesMeta": {
70+
"class-transformer": { "optional": true },
71+
"class-validator": { "optional": true },
72+
"@nestjs/event-emitter": { "optional": true },
73+
"@nestjs/throttler": { "optional": true }
74+
},
75+
"dependencies": {
76+
"otplib": "^12.0.0",
77+
"qrcode": "^1.5.0",
78+
"bcrypt": "^5.0.0"
79+
},
80+
"devDependencies": {
81+
"@eslint/js": "^10.0.1",
82+
"@nestjs/common": "^11.0.0",
83+
"@nestjs/core": "^11.0.0",
84+
"@nestjs/jwt": "^11.0.0",
85+
"@nestjs/passport": "^11.0.0",
86+
"@nestjs/event-emitter": "^3.0.0",
87+
"@nestjs/throttler": "^6.0.0",
88+
"@nestjs/testing": "^11.0.0",
89+
"@types/bcrypt": "^5.0.0",
90+
"@types/node": "^20.19.37",
91+
"@types/passport-jwt": "^4.0.0",
92+
"@types/passport-local": "^1.0.0",
93+
"@types/qrcode": "^1.5.0",
94+
"@vitest/coverage-v8": "^4.1.0",
95+
"class-transformer": "^0.5.1",
96+
"class-validator": "^0.14.1",
97+
"eslint": "^10.0.3",
98+
"eslint-config-prettier": "^10.1.8",
99+
"eslint-plugin-prettier": "^5.5.5",
100+
"passport": "^0.7.0",
101+
"passport-jwt": "^4.0.1",
102+
"passport-local": "^1.0.0",
103+
"prettier": "^3.8.1",
104+
"reflect-metadata": "^0.2.2",
105+
"rxjs": "^7.8.0",
106+
"typescript": "^5.5.0",
107+
"typescript-eslint": "^8.57.1",
108+
"vitest": "^4.1.0"
109+
}
110+
}

0 commit comments

Comments
 (0)