@ciscode/authentication-kit 1.1.0 → 1.1.1

package/README.md

@@ -1,48 +1,31 @@
-Auth Service (Express · JWT · Multi‑Tenant · RBAC)
-Internal package — private to the company.
-This package is not published on npmjs. Install it only from the company’s Azure Artifacts feed using a project or user-level .npmrc.
+Auth Service (NestJS, JWT, Multi-tenant, 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.
 
-Authentication & authorization service for Node/Express apps.
-Provides local email/password auth with lockout, JWT access tokens + refresh, tenant scoping, RBAC, and optional Microsoft Entra (Azure AD) OAuth.
+Authentication and authorization module for NestJS apps.
+Provides local email/password auth with lockout, JWT access tokens and refresh, tenant scoping, RBAC, and optional OAuth (Microsoft Entra, Google, Facebook).
 
 Features
 Local auth (email/password) with account lockout policy.
 JWT access tokens (Bearer) and refresh endpoint (cookie or body).
 Multi-tenant scope on requests.
-RBAC (roles → permission strings).
-Microsoft Entra (Azure AD) OAuth (optional).
+RBAC (roles -> permission strings).
+Microsoft Entra (Azure AD), Google, Facebook OAuth (optional).
 MongoDB/Mongoose models.
+
 Routes are mounted under:
 
 /api/auth (auth, password reset)
 /api/users (user admin)
 /api/auth/roles and /api/auth/permissions (RBAC)
-Installation (Azure Artifacts only)
-1) Configure .npmrc
-Do not commit real tokens. Prefer ~/.npmrc or generate .npmrc in CI using secrets.
-
-For developers (user-level ~/.npmrc):
-
-registry=https://registry.npmjs.org/
-
-# Route @ciscodeapps scope to the private feed
-@ciscodeapps:registry=https://pkgs.dev.azure.com/CISCODEAPPS/Templates/_packaging/testfeed/npm/registry/
+/api/admin (admin actions)
 
-//pkgs.dev.azure.com/CISCODEAPPS/Templates/_packaging/testfeed/npm/registry/:_authToken=${AZURE_ARTIFACTS_PAT}
-always-auth=true
-Set the token as an environment variable before installing:
+Installation
 
-export AZURE_ARTIFACTS_PAT="<your PAT with Packaging:Read>"
-You can also use the username/_password form:
+1) Install the package
+npm i @ciscode/authentication-kit
 
-//pkgs.dev.azure.com/...:username=AzureDevOps
-//pkgs.dev.azure.com/...:_password=${BASE64_PAT}
-//pkgs.dev.azure.com/...:email=not-used@localhost
-where BASE64_PAT=$(printf %s "$AZURE_ARTIFACTS_PAT" | base64).
-
-2) Install the package
-npm i @ciscodeapps/auth-service
-3) Required environment variables (host app)
+2) Required environment variables (host app)
 Create a .env in the host project:
 
 # Server
@@ -64,61 +47,59 @@ MAX_FAILED_LOGIN_ATTEMPTS=5
 ACCOUNT_LOCK_TIME_MINUTES=15
 
 # (Optional) Microsoft Entra ID (Azure AD)
-MICROSOFT_TENANT=organizations
+MICROSOFT_TENANT_ID=common
 MICROSOFT_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 MICROSOFT_CLIENT_SECRET=your-secret
 MICROSOFT_CALLBACK_URL=${BASE_URL}/api/auth/microsoft/callback
-Use inside an existing Express app
-Your package exports an Express app that already parses JSON, connects to Mongo, and mounts its routes. Just mount it:
 
-// server.js (host app)
-require('dotenv').config();
-const express = require('express');
-const authApp = require('@ciscodeapps/auth-service');
+Use inside an existing Nest app
+The module connects to Mongo on init and mounts its controllers.
+
+// app.module.ts (host app)
+import { Module } from '@nestjs/common';
+import { AuthKitModule } from '@ciscode/authentication-kit';
+
+@Module({
+  imports: [AuthKitModule]
+})
+export class AppModule {}
 
-const app = express();
-app.use(authApp);           // exposes /api/auth, /api/users, /api/auth/roles, /api/auth/permissions
+If you need to run it standalone, build and start the package:
 
-app.get('/health', (_, res) => res.json({ ok: true }));
-app.listen(process.env.PORT || 3000, () =>
-  console.log('Host app on', process.env.PORT || 3000)
-);
-Prefer mounting the service. If you need to run it standalone, you can also start this package directly (it calls connectDB() on import).
+npm run build
+npm start
 
-What’s included (routes & behavior)
+What is included (routes and behavior)
 Auth
-POST /api/auth/register – Create a user (email/password).
-POST /api/auth/login – Local login. On success, returns accessToken and may set a refreshToken httpOnly cookie.
-POST /api/auth/verify-otp – If OTP/step-up is enabled, verifies the code and completes login.
-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).
-PATCH /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.
+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.
 Users
-GET /api/users – List users (tenant-scoped, paginated).
-POST /api/users – Create a user (requires permission).
+GET /api/users - List users (tenant-scoped, paginated).
+POST /api/users - Create a user.
 Additional CRUD endpoints as exposed by controllers.
-Roles & Permissions
-GET/POST /api/auth/roles – Manage roles (name, tenantId, permissions: string[]).
-GET /api/auth/permissions – List permission strings and metadata.
+Roles and Permissions
+GET/POST /api/auth/roles - Manage roles (name, tenantId, permissions: string[]).
+GET /api/auth/permissions - List permission strings and metadata.
+
 Protecting your own routes (host app)
-const authenticate = require('@ciscodeapps/auth-service/src/middleware/authenticate'); // JWT
-const { hasPermission } = require('@ciscodeapps/auth-service/src/middleware/rbac.middleware'); // RBAC
-
-app.get('/reports',
-  authenticate,
-  hasPermission('reports:read'),
-  (req, res) => res.json({ ok: true })
-);
+import { UseGuards } from '@nestjs/common';
+import { AuthenticateGuard, hasPermission } from '@ciscode/authentication-kit';
+
+@UseGuards(AuthenticateGuard, hasPermission('reports:read'))
+@Get('reports')
+getReports() {
+  return { ok: true };
+}
+
 Tenant scope comes from the JWT payload (e.g., tenantId) and is used inside controllers/guards to filter queries.
 
 Quick start (smoke tests)
-Start your host app:
-
-node server.js
-Register & Login
+Start your host app, then create a user and log in:
 
-curl -X POST http://localhost:3000/api/auth/register \
+curl -X POST http://localhost:3000/api/users \
   -H 'Content-Type: application/json' \
   -d '{"email":"a@b.com","password":"Secret123!","tenantId":"t-001","name":"Alice"}'
 
@@ -126,17 +107,20 @@ curl -X POST http://localhost:3000/api/auth/login \
   -H 'Content-Type: application/json' \
   -d '{"email":"a@b.com","password":"Secret123!","tenantId":"t-001"}'
 # => { "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 → complete sign-in.
+
+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)
@@ -151,7 +135,7 @@ CI/CD (Azure Pipelines)
 
 Security notes
 Never commit real PATs. Use env vars or CI secrets.
-Run behind HTTPS. Rotate JWT & refresh secrets periodically.
+Run behind HTTPS. Rotate JWT and refresh secrets periodically.
 Limit login attempts; log auth events for auditing.
 License
-Internal — Company proprietary.
+Internal - Company proprietary.

package/package.json

@@ -1,45 +1,70 @@
 {
-    "name": "@ciscode/authentication-kit",
-    "publishConfig": {
-        "access": "public"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/CISCODE-MA/authentication-kit.git"
-    },
-    "version": "1.1.0",
-    "description": "A login library with local login, Microsoft Entra ID authentication, password reset, and roles/permissions for multi-tenant applications.",
-    "main": "src/index.js",
-    "scripts": {
-        "start": "node src/index.js",
-        "test": "echo \"No tests defined\" && exit 0",
-        "release": "semantic-release"
-    },
-    "keywords": [
-        "login",
-        "authentication",
-        "microsoft-oauth",
-        "password-reset",
-        "roles",
-        "permissions",
-        "multi-tenant"
-    ],
-    "author": "Ciscode",
-    "license": "MIT",
-    "dependencies": {
-        "bcryptjs": "^2.4.3",
-        "crypto": "^1.0.1",
-        "dotenv": "^16.0.3",
-        "express": "^4.18.2",
-        "jsonwebtoken": "^9.0.0",
-        "mongoose": "^7.0.0",
-        "mongoose-paginate-v2": "^1.7.1",
-        "nodemailer": "^6.9.1",
-        "passport": "^0.6.0",
-        "passport-azure-ad-oauth2": "^0.0.4",
-        "passport-local": "^1.0.0"
-    },
-    "devDependencies": {
-        "semantic-release": "^25.0.2"
-    }
+  "name": "@ciscode/authentication-kit",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CISCODE-MA/AuthKit.git"
+  },
+  "version": "1.1.1",
+  "description": "A login library with local login, Microsoft Entra ID authentication, password reset, and roles/permissions for multi-tenant applications.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/standalone.js",
+    "test": "echo \"No tests defined\" && exit 0",
+    "release": "semantic-release"
+  },
+  "keywords": [
+    "login",
+    "authentication",
+    "microsoft-oauth",
+    "password-reset",
+    "roles",
+    "permissions",
+    "multi-tenant"
+  ],
+  "author": "Ciscode",
+  "license": "MIT",
+  "dependencies": {
+    "@nestjs/common": "^10.4.0",
+    "@nestjs/core": "^10.4.0",
+    "@nestjs/platform-express": "^10.4.0",
+    "axios": "^1.7.7",
+    "bcryptjs": "^2.4.3",
+    "cookie-parser": "^1.4.6",
+    "dotenv": "^16.0.3",
+    "express": "^4.18.2",
+    "jsonwebtoken": "^9.0.0",
+    "jwks-rsa": "^3.1.0",
+    "mongoose": "^7.0.0",
+    "mongoose-paginate-v2": "^1.7.1",
+    "nodemailer": "^7.0.12",
+    "passport": "^0.6.0",
+    "passport-azure-ad-oauth2": "^0.0.4",
+    "passport-facebook": "^3.0.0",
+    "passport-google-oauth20": "^2.0.0",
+    "passport-local": "^1.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  },
+  "devDependencies": {
+    "@types/cookie-parser": "^1.4.6",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.6",
+    "@types/node": "^20.12.12",
+    "@types/passport-facebook": "^3.0.4",
+    "@types/passport-google-oauth20": "^2.0.15",
+    "@types/passport-local": "^1.0.38",
+    "semantic-release": "^25.0.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2"
+  }
 }

package/.github/workflows/ci .yml

@@ -1,36 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [master, develop]
-  push:
-    branches: [develop]
-
-permissions:
-  contents: read
-
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: npm
-          registry-url: https://registry.npmjs.org/
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint --if-present
-
-      - name: Test
-        run: npm test --if-present
-
-      - name: Build
-        run: npm run build --if-present

package/.github/workflows/publish.yml

@@ -1,30 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    tags:
-      - "v*.*.*"
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org/
-          cache: npm
-      - name: Install dependencies
-        run: npm ci
-      - name: Build library 
-        run: npm run build:lib --if-present
-      - name: Publish to npm
-        run: npm publish --access public --provenance
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CODE_OF_CONDUCT

@@ -1,38 +0,0 @@
-# Code of Conduct
-
-This project adheres to the Contributor Covenant Code of Conduct.
-
----
-
-## Our Pledge
-
-We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity.
-
----
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment include:
-- Being respectful and inclusive
-- Giving and accepting constructive feedback
-- Focusing on what is best for the community
-
-Examples of unacceptable behavior include:
-- Harassment or discriminatory language
-- Personal attacks or trolling
-- Publishing private information without consent
-
----
-
-## Enforcement
-
-Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior.
-
-Instances of abusive behavior may be reported to the maintainers through private communication channels.
-
----
-
-## Attribution
-
-This Code of Conduct is adapted from the Contributor Covenant  
-version 2.1 — https://www.contributor-covenant.org/

package/CONTRIBUTING.md

@@ -1,40 +0,0 @@
-# Contributing
-
-Thank you for your interest in contributing to this project.
-
-Contributions of all kinds are welcome, including bug reports, feature requests, documentation improvements, and code contributions.
-
----
-
-## How to Contribute
-
-1. Fork the repository
-2. Create a new branch from `main`
-3. Make your changes
-4. Add or update tests where applicable
-5. Ensure existing tests pass
-6. Open a pull request with a clear description
-
----
-
-## Guidelines
-
-- Keep changes focused and minimal
-- Follow existing code style and conventions
-- Avoid breaking backward compatibility when possible
-- Write clear commit messages
-- Do not include secrets, credentials, or tokens
-
----
-
-## Reporting Bugs
-
-When reporting bugs, please include:
-- A clear description of the issue
-- Steps to reproduce
-- Expected vs actual behavior
-- Relevant logs or error messages (redacted if needed)
-
----
-
-By contributing, you agree that your contributions will be licensed under the same license as the project.

package/SECURITY

@@ -1,31 +0,0 @@
-# Security Policy
-
-Security is taken seriously in this project.
-
-If you discover a security vulnerability, please **do not open a public issue**.
-
----
-
-## Reporting a Vulnerability
-
-Please report security issues privately by contacting the maintainers using one of the following methods:
-
-- Email the address listed in the repository’s contact or maintainer information
-- Use private disclosure channels if available on the hosting platform
-
-When reporting, please include:
-- A description of the vulnerability
-- Steps to reproduce
-- Potential impact
-- Any suggested mitigations (if known)
-
----
-
-## Security Best Practices
-
-- Never commit secrets or credentials
-- Use strong, rotated secrets for JWT signing
-- Run services behind HTTPS
-- Apply rate limiting and monitoring in production environments
-
-We appreciate responsible disclosure and will work to address issues promptly.

package/azure-pipelines.yml

@@ -1,100 +0,0 @@
-trigger:
-  - main
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-variables:
-  - group: BE  # AZURE_ARTIFACTS_PAT lives here; add NPM_TOKEN and (optionally) GH_PAT as secrets
-
-# Optional toggles (default = behave exactly like your old pipeline: publish only to Azure Artifacts)
-parameters:
-  - name: pushToGitHub
-    type: boolean
-    default: false
-  - name: publishToNpm
-    type: boolean
-    default: false
-  - name: packagePath
-    type: string
-    default: 'modules/login'
-
-steps:
-  # Allows pushing back to GitHub if pushToGitHub=true (we'll still use GH_PAT if provided)
-  - checkout: self
-    persistCredentials: true
-    displayName: 'Checkout (allows push when enabled)'
-
-  # 1) Use Node.js (unchanged)
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '20.x'
-    displayName: 'Use Node.js'
-
-  # 2) Authenticate with Azure Artifacts (unchanged)
-  - script: |
-      echo "Setting up npm authentication for Azure Artifacts..."
-      echo "//pkgs.dev.azure.com/CISCODEAPPS/Templates/_packaging/testfeed/npm/registry/:_authToken=$(AZURE_ARTIFACTS_PAT)" > ~/.npmrc
-      npm set registry "https://pkgs.dev.azure.com/CISCODEAPPS/Templates/_packaging/testfeed/npm/registry/"
-    displayName: 'Authenticate with Azure Artifacts'
-
-  # 3) Bump + publish to Azure Artifacts (mandatory)
-  - script: |
-      set -e
-      echo "Bumping package version before publishing login..."
-      cd ${{ parameters.packagePath }}
-      npm version patch --no-git-tag-version
-
-      # capture for optional steps
-      NEW_VERSION=$(node -p "require('./package.json').version")
-      PKG_NAME=$(node -p "require('./package.json').name")
-      echo "Decided version: ${NEW_VERSION} for ${PKG_NAME}"
-      echo "##vso[task.setvariable variable=NEW_VERSION]$NEW_VERSION"
-      echo "##vso[task.setvariable variable=PKG_NAME]$PKG_NAME"
-
-      # sanity: see what will be published
-      npm pack --dry-run
-
-      # publish to Azure Artifacts (mandatory)
-      npm publish --registry=https://pkgs.dev.azure.com/CISCODEAPPS/Templates/_packaging/testfeed/npm/registry/
-    displayName: 'Publish authentication module (Azure Artifacts - mandatory)'
-
-  # OPTIONAL: push the version bump back to GitHub
-  - ${{ if eq(parameters.pushToGitHub, true) }}:
-    - script: |
-        set -e
-        cd ${{ parameters.packagePath }}
-
-        # bot identity for the commit
-        git config user.name "azure-pipelines[bot]"
-        git config user.email "azure-pipelines-bot@example.local"
-
-        # If a GitHub PAT is provided, use it to ensure push works (esp. with GitHub App connections)
-        if [ -n "$(GH_PAT)" ]; then
-          echo "Using GH_PAT to authenticate push..."
-          git remote set-url origin "https://x-access-token:$(GH_PAT)@github.com/CISCODE-MA/auth_package"
-        fi
-
-        git add package.json package-lock.json || true
-        git commit -m "chore(login): bump $(PKG_NAME) to v$(NEW_VERSION) [skip ci]" || echo "No changes to commit"
-        git push origin HEAD:$(Build.SourceBranchName)
-      displayName: 'Push version bump to GitHub (optional)'
-
-  # OPTIONAL: publish same version to npm public (with pre-check)
-  - ${{ if eq(parameters.publishToNpm, true) }}:
-    - script: |
-        set -e
-        echo "Switching npm auth to npm public..."
-        rm -f ~/.npmrc || true
-        echo "//registry.npmjs.org/:_authToken=$(NPM_TOKEN)" > ~/.npmrc
-        npm set registry "https://registry.npmjs.org/"
-
-        cd ${{ parameters.packagePath }}
-
-        # Skip if the exact version already exists on npm
-        if npm view "$(PKG_NAME)@$(NEW_VERSION)" version >/dev/null 2>&1; then
-          echo "$(PKG_NAME)@$(NEW_VERSION) already exists on npm; skipping publish."
-        else
-          npm publish --access public
-        fi
-      displayName: 'Publish to npm public (optional)'

package/src/config/db.config.js

@@ -1,21 +0,0 @@
-const mongoose = require('mongoose');
-require('dotenv').config();
-
-// Optionally, set strictQuery per Mongoose recommendations
-mongoose.set('strictQuery', false);
-
-const connectDB = async () => {
-  try {
-    const mongoURI = process.env.MONGO_URI_T;
-    if (!mongoURI) {
-      throw new Error('MONGO_URI is not defined in the environment variables.');
-    }
-    await mongoose.connect(mongoURI);
-    console.log("MongoDB Connected...");
-  } catch (error) {
-    console.error("MongoDB Connection Error:", error);
-    process.exit(1);
-  }
-};
-
-module.exports = connectDB;