@ciscode/authentication-kit 1.1.5 → 1.2.0

package/README.md

@@ -1,139 +1,474 @@
-Auth Service (NestJS, JWT, RBAC)
-Internal package - private to the company.
-This package is not published on npmjs. Install it only from the company Azure Artifacts feed using a project or user-level .npmrc.
+# AuthKit (NestJS Auth Package)
 
-Authentication and authorization module for NestJS apps.
-Provides local email/password auth with lockout, JWT access tokens and refresh, RBAC, and optional OAuth (Microsoft Entra, Google, Facebook).
+A production-ready, comprehensive authentication/authorization kit for NestJS with local auth, OAuth (Google/Microsoft/Facebook), JWT tokens, RBAC, admin user management, email verification, and password reset.
 
-Features
-Local auth (email/password) with account lockout policy.
-JWT access tokens (Bearer) and refresh endpoint (cookie or body).
-RBAC (roles -> permission strings).
-Microsoft Entra (Azure AD), Google, Facebook OAuth (optional).
-MongoDB/Mongoose models.
+## Features
 
-Routes are mounted under:
+- **Local Authentication:** Email + password registration & login
+- **OAuth Providers:**
+  - Google (ID Token validation + Authorization Code exchange)
+  - Microsoft (Entra ID with JWKS verification)
+  - Facebook (App token validation)
+  - Web redirect flow (Passport)
+  - Mobile token/code exchange
+- **JWT Management:**
+  - Access tokens (stateless, short-lived)
+  - Refresh tokens (long-lived JWTs with automatic invalidation on password change)
+  - Email verification tokens (JWT-based links)
+  - Password reset tokens (JWT-based links)
+- **Email Verification:** Required before login
+- **Password Reset:** JWT-secured reset link
+- **Admin User Management:** Create, list, ban/unban, delete, assign roles
+- **RBAC (Role-Based Access Control):**
+  - Roles linked to users
+  - Permissions linked to roles
+  - Roles automatically included in JWT payload (Ids)
+  - Fine-grained access control
+- **Host App Control:** Package uses host app's Mongoose connection (no DB lock-in)
 
-/api/auth (auth, password reset)
-/api/users (user admin)
-/api/auth/roles and /api/auth/permissions (RBAC)
-/api/admin (admin actions)
+## Install
 
-Installation
-
-1) Install the package
+```bash
 npm i @ciscode/authentication-kit
+```
 
-2) Required environment variables (host app)
-Create a .env in the host project:
+## Host App Setup
 
-# Server
-PORT=3000
-NODE_ENV=development
-BASE_URL=http://localhost:3000
+### 1. Environment Variables
 
-# Database (the service connects to this on startup)
-MONGO_URI_T=mongodb://127.0.0.1:27017/auth_service
+```env
+# Database
+MONGO_URI=mongodb://127.0.0.1:27017/app_db
 
-# JWT
-JWT_SECRET=change_me
+# JWT Configuration
+JWT_SECRET=your_super_secret_key_change_this
 JWT_ACCESS_TOKEN_EXPIRES_IN=15m
-JWT_REFRESH_SECRET=change_me_too
+JWT_REFRESH_SECRET=your_refresh_secret_change_this
 JWT_REFRESH_TOKEN_EXPIRES_IN=7d
+JWT_EMAIL_SECRET=your_email_secret_change_this
+JWT_EMAIL_TOKEN_EXPIRES_IN=1d
+JWT_RESET_SECRET=your_reset_secret_change_this
+JWT_RESET_TOKEN_EXPIRES_IN=1h
+
+# Email (SMTP)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your-email@gmail.com
+SMTP_PASS=your-app-password
+SMTP_SECURE=false
+FROM_EMAIL=noreply@yourapp.com
+
+# Frontend URL (for email links)
+FRONTEND_URL=http://localhost:3000
 
-# Lockout policy
-MAX_FAILED_LOGIN_ATTEMPTS=5
-ACCOUNT_LOCK_TIME_MINUTES=15
+# Google OAuth
+GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback
 
-# (Optional) Microsoft Entra ID (Azure AD)
-MICROSOFT_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-MICROSOFT_CLIENT_SECRET=your-secret
-MICROSOFT_CALLBACK_URL=${BASE_URL}/api/auth/microsoft/callback
+# Microsoft/Entra ID OAuth
+MICROSOFT_CLIENT_ID=your-microsoft-client-id
+MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
+MICROSOFT_CALLBACK_URL=http://localhost:3000/api/auth/microsoft/callback
+MICROSOFT_TENANT_ID=common  # Optional, defaults to 'common'
 
-Use inside an existing Nest app
-The module connects to Mongo on init and mounts its controllers.
+# Facebook OAuth
+FB_CLIENT_ID=your-facebook-app-id
+FB_CLIENT_SECRET=your-facebook-app-secret
+FB_CALLBACK_URL=http://localhost:3000/api/auth/facebook/callback
 
-// app.module.ts (host app)
-import { Module } from '@nestjs/common';
-import { AuthKitModule } from '@ciscode/authentication-kit';
+# Environment
+NODE_ENV=development
+```
+
+### 2. Host app example
+
+```typescript
+import { Module, OnModuleInit } from '@nestjs/common';
+import { MongooseModule } from '@nestjs/mongoose';
+import { AuthKitModule, SeedService } from '@ciscode/authentication-kit';
 
 @Module({
-  imports: [AuthKitModule]
+  imports: [MongooseModule.forRoot(process.env.MONGO_URI), AuthKitModule],
 })
-export class AppModule {}
-
-If you need to run it standalone, build and start the package:
-
-npm run build
-npm start
-
-What is included (routes and behavior)
-Auth
-POST /api/auth/login - Local login. On success, returns accessToken and may set a refreshToken httpOnly cookie.
-POST /api/auth/refresh-token - New access token from a valid refresh token (cookie or body).
-POST /api/auth/request-password-reset - Sends a reset token (e.g., by email).
-POST /api/auth/reset-password - Consumes the reset token and sets a new password.
-GET /api/auth/microsoft - GET /api/auth/microsoft/callback - Optional Microsoft Entra OAuth; issues first-party tokens.
-Note: If the Microsoft ID token does not include an email, the response includes `profileIncomplete: true`.
-Users
-GET /api/users - List users (paginated).
-POST /api/users - Create a user.
-Additional CRUD endpoints as exposed by controllers.
-If `profileIncomplete: true`, update the user profile (e.g., set `email`) via `PUT /api/users/:id`.
-Roles and Permissions
-GET/POST /api/auth/roles - Manage roles (name, permissions: string[]).
-GET /api/auth/permissions - List permission strings and metadata.
-
-Protecting your own routes (host app)
-import { UseGuards } from '@nestjs/common';
-import { AuthenticateGuard, hasPermission } from '@ciscode/authentication-kit';
-
-@UseGuards(AuthenticateGuard, hasPermission('reports:read'))
-@Get('reports')
-getReports() {
-  return { ok: true };
-}
-
-Quick start (smoke tests)
-Start your host app, then create a user and log in:
-
-curl -X POST http://localhost:3000/api/users \
-  -H 'Content-Type: application/json' \
-  -d '{"email":"a@b.com","password":"Secret123!","name":"Alice"}'
-
-curl -X POST http://localhost:3000/api/auth/login \
-  -H 'Content-Type: application/json' \
-  -d '{"email":"a@b.com","password":"Secret123!"}'
-# => { "accessToken": "...", "refreshToken": "..." }
-
-Call a protected route
-
-ACCESS=<paste_access_token_here>
-curl http://localhost:3000/api/users -H "Authorization: Bearer $ACCESS"
-
-Refresh token
-
-curl -X POST http://localhost:3000/api/auth/refresh-token \
-  -H 'Content-Type: application/json' \
-  -d '{"refreshToken":"<paste_refresh_token_here>"}'
-# => { "accessToken": "..." }
-
-Microsoft OAuth (optional) - Visit: http://localhost:3000/api/auth/microsoft to complete sign-in.
-- Callback: ${BASE_URL}/api/auth/microsoft/callback returns tokens (and may set the refresh cookie).
-
-CI/CD (Azure Pipelines)
-# azure-pipelines.yml (snippet)
-- task: npmAuthenticate@0
-  inputs:
-    workingFile: .npmrc  # optional; the task wires npm auth for subsequent steps
-
-- script: npm ci
-  displayName: Install deps
-(For GitHub Actions, write a ~/.npmrc with the token from secrets.AZURE_ARTIFACTS_PAT before npm ci.)
-
-Security notes
-Never commit real PATs. Use env vars or CI secrets.
-Run behind HTTPS. Rotate JWT and refresh secrets periodically.
-Limit login attempts; log auth events for auditing.
-License
-Internal - Company proprietary.
+export class AppModule implements OnModuleInit {
+  constructor(private readonly seed: SeedService) {}
+
+  async onModuleInit() {
+    await this.seed.seedDefaults();
+  }
+}
+```
+
+> NOTES:
+>
+> The AuthKit, by default seeds database with default roles and permissions once the host app is bootstraped (logs are generated for info)
+> Default user role, on first register, is 'user' ... Mongoose needs Id to do this relation (the app MUST seed db from the package before anything)
+
+## API Routes
+
+### Local Auth Routes (Public)
+
+```
+POST   /api/auth/register
+POST   /api/auth/verify-email
+POST   /api/auth/resend-verification
+POST   /api/auth/login
+POST   /api/auth/refresh-token
+POST   /api/auth/forgot-password
+POST   /api/auth/reset-password
+DELETE /api/auth/account (protected)
+```
+
+### OAuth Routes - Mobile Exchange (Public)
+
+Exchange OAuth provider tokens for app tokens:
+
+```txt
+POST /api/auth/oauth/google       { idToken?: string, code?: string }
+POST /api/auth/oauth/microsoft    { idToken: string }
+POST /api/auth/oauth/facebook     { accessToken: string }
+```
+
+### OAuth Routes - Web Redirect (Public)
+
+Passport-based OAuth flow for web browsers:
+
+```txt
+GET /api/auth/google                    | Google OAuth
+GET /api/auth/google/callback           | Google Redirect (After login)
+GET /api/auth/microsoft                 | Microsoft OAuth
+GET /api/auth/microsoft/callback        | Microsoft Redirect (After login)
+GET /api/auth/facebook                  | Facebook OAuth
+GET /api/auth/facebook/callback         | Facebook Redirect (After login)
+```
+
+### Admin Routes - Users (Protected with @Admin())
+
+```txt
+POST   /api/admin/users                         |Create user
+GET    /api/admin/users?email=...&username=...  |List users (with filters)
+PATCH  /api/admin/users/:id/ban                 |Ban user
+PATCH  /api/admin/users/:id/unban               |Unban user
+PATCH  /api/admin/users/:id/roles               |Update user roles
+DELETE /api/admin/users/:id                     |Delete user
+```
+
+### Admin Routes - Roles (Protected with @Admin())
+
+```txt
+POST   /api/admin/roles                    Create role
+GET    /api/admin/roles                    List all roles
+PUT    /api/admin/roles/:id                Update role name
+PUT    /api/admin/roles/:id/permissions    Set role permissions
+DELETE /api/admin/roles/:id                Delete role
+```
+
+### Admin Routes - Permissions (Protected with @Admin())
+
+```txt
+POST   /api/admin/permissions              Create permission
+GET    /api/admin/permissions              List all permissions
+PUT    /api/admin/permissions/:id          Update permission
+DELETE /api/admin/permissions/:id          Delete permission
+```
+
+## Usage Examples
+
+### Register
+
+**Request:**
+
+```json
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "fullname": {
+    "fname": "Test",
+    "lname": "User"
+  },
+  "username": "Userrr",
+  "email": "user@example.com",
+  "password": "Pa$$word!",
+  "phoneNumber": "+1234567890",
+  "avatar": "https://example.com/avatar.jpg"
+}
+```
+
+**Response:**
+
+```json
+{
+  "id": "507f1f77bcf86cd799439011",
+  "email": "user@example.com"
+}
+```
+
+### Login
+
+**Request:**
+
+```json
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "Pa$$word!"
+}
+```
+
+**Response:**
+
+```json
+{
+  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+_Note: `refreshToken` is also set in httpOnly cookie_
+
+### Verify Email
+
+**Request:**
+
+```json
+POST /api/auth/verify-email
+Content-Type: application/json
+
+{
+  "token": "email-verification-token-from-email"
+}
+```
+
+**Response:**
+
+```json
+{
+  "ok": true
+}
+```
+
+### Refresh Token
+
+**Request (from body):**
+
+```json
+POST /api/auth/refresh-token
+Content-Type: application/json
+
+{
+  "refreshToken": "refresh-token-value"
+}
+```
+
+**OR (from cookie - automatic):**
+
+```json
+POST /api/auth/refresh-token
+Cookie: refreshToken=refresh-token-value
+```
+
+**Response:**
+
+```json
+{
+  "accessToken": "new-access-token",
+  "refreshToken": "new-refresh-token"
+}
+```
+
+### OAuth Google (Mobile Exchange)
+
+**Request (with ID Token):**
+
+```json
+POST /api/auth/oauth/google
+Content-Type: application/json
+
+{
+  "idToken": "google-id-token-from-client"
+}
+```
+
+**OR (with Authorization Code):**
+
+```json
+POST /api/auth/oauth/google
+Content-Type: application/json
+
+{
+  "code": "authorization-code-from-google"
+}
+```
+
+**Response:**
+
+```json
+{
+  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+### Delete Account
+
+**Request:**
+
+```json
+DELETE /api/auth/account
+Authorization: Bearer access-token
+```
+
+**Response:**
+
+```json
+{
+  "ok": true
+}
+```
+
+## Guards & Decorators
+
+**AuthenticateGuard:** Protects routes that require authentication. (No Access if not authenticated)
+**Admin Decorator:** Restricts routes to admin users only. (No Access if not an admin)
+
+## JWT Token Structure
+
+### Access Token Payload
+
+```json
+{
+  "sub": "user-id",
+  "roles": ["ids"],
+  "iat": 1672531200,
+  "exp": 1672531900
+}
+```
+
+### Refresh Token Payload
+
+```json
+{
+  "sub": "user-id",
+  "purpose": "refresh",
+  "iat": 1672531200,
+  "exp": 1672617600
+}
+```
+
+**Security Note:** Refresh tokens are automatically invalidated if user changes password. The `passwordChangedAt` timestamp is checked during token refresh.
+
+## Seeding
+
+On app startup via `onModuleInit()`, the following are created:
+
+**Roles:**
+
+- `admin` - Full permissions
+- `user` - No default permissions
+
+**Permissions:**
+
+- `users:manage` - Create, list, ban, delete users
+- `roles:manage` - Create, list, update, delete roles
+- `permissions:manage` - Create, list, update, delete permissions
+
+All permissions are assigned to the `admin` role.
+
+## User Model
+
+```typescript
+{
+  _id: ObjectId,
+  fullname: {
+    fname: string,
+    lname: string
+  },
+  username: string (unique, 3-30 chars),
+  email: string (unique, validated),
+  phoneNumber?: string (unique, 10-14 digits),
+  avatar?: string (default: 'default.jpg'),
+  password: string (hashed, min 6 chars),
+  roles: ObjectId[] (references Role),
+  isVerified: boolean (default: false),
+  isBanned: boolean (default: false),
+  passwordChangedAt: Date,
+  createdAt: Date,
+  updatedAt: Date
+}
+```
+
+## Role Model
+
+```typescript
+{
+  _id: ObjectId,
+  name: string (unique),
+  permissions: ObjectId[] (references Permission),
+  createdAt: Date,
+  updatedAt: Date
+}
+```
+
+## Permission Model
+
+```typescript
+{
+  _id: ObjectId,
+  name: string (unique),
+  description?: string,
+  createdAt: Date,
+  updatedAt: Date
+}
+```
+
+## Important Notes
+
+- **Database:** AuthKit does NOT manage MongoDB connection. Your host app must provide the connection via `MongooseModule.forRoot()`.
+- **Stateless:** JWTs are stateless; refresh tokens are signed JWTs (not stored in DB).
+- **Email Verification Required:** Users cannot login until they verify their email.
+- **Password Changes Invalidate Tokens:** All refresh tokens become invalid immediately after password change.
+- **OAuth Auto-Registration:** Users logging in via OAuth are automatically created with verified status.
+- **Cookie + Body Support:** Refresh tokens can be passed via httpOnly cookies OR request body.
+- **Admin Access:** Routes under `/api/admin/*` require the `admin` role (enforced by `@Admin()` decorator).
+
+## Error Handling
+
+The package throws errors with descriptive messages. Your host app should catch and format them appropriately:
+
+```typescript
+try {
+  await authService.login(dto);
+} catch (error) {
+  // Possible errors:
+  // "Invalid credentials."
+  // "Account banned."
+  // "Email not verified."
+  // "User not found."
+  // "JWT_SECRET is not set"
+  // etc.
+}
+```
+
+## Development
+
+```bash
+npm run build      # Compile TypeScript + alias paths
+npm run start      # Run standalone (if applicable)
+npm run test       # Run tests (currently no tests defined)
+```
+
+## License
+
+MIT
+
+## Author
+
+Ciscode
+
+---
+
+**Version:** 1.2.0

package/dist/auth-kit.module.d.ts

@@ -1,7 +1,9 @@
 import 'dotenv/config';
-import { MiddlewareConsumer, NestModule, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
-export declare class AuthKitModule implements NestModule, OnModuleInit, OnModuleDestroy {
-    onModuleInit(): Promise<void>;
-    onModuleDestroy(): Promise<void>;
+import { MiddlewareConsumer, NestModule, OnModuleInit } from '@nestjs/common';
+import { OAuthService } from './services/oauth.service';
+export declare class AuthKitModule implements NestModule, OnModuleInit {
+    private readonly oauth;
+    constructor(oauth: OAuthService);
+    onModuleInit(): void;
     configure(consumer: MiddlewareConsumer): void;
 }