@ciscode/authentication-kit 1.0.33

package/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: CD - Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - 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: Build library
+        run: npm run build:lib
+
+      - name: Release
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm run release

package/CODE_OF_CONDUCT

@@ -0,0 +1,38 @@
+# 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

@@ -0,0 +1,40 @@
+# 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/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 Ciscode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+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.
+
+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.
+
+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).
+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/
+
+//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:
+
+export AZURE_ARTIFACTS_PAT="<your PAT with Packaging:Read>"
+You can also use the username/_password form:
+
+//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)
+Create a .env in the host project:
+
+# Server
+PORT=3000
+NODE_ENV=development
+BASE_URL=http://localhost:3000
+
+# Database (the service connects to this on startup)
+MONGO_URI_T=mongodb://127.0.0.1:27017/auth_service
+
+# JWT
+JWT_SECRET=change_me
+JWT_ACCESS_TOKEN_EXPIRES_IN=15m
+JWT_REFRESH_SECRET=change_me_too
+JWT_REFRESH_TOKEN_EXPIRES_IN=7d
+
+# Lockout policy
+MAX_FAILED_LOGIN_ATTEMPTS=5
+ACCOUNT_LOCK_TIME_MINUTES=15
+
+# (Optional) Microsoft Entra ID (Azure AD)
+MICROSOFT_TENANT=organizations
+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');
+
+const app = express();
+app.use(authApp);           // exposes /api/auth, /api/users, /api/auth/roles, /api/auth/permissions
+
+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).
+
+What’s included (routes & 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.
+Users
+GET /api/users – List users (tenant-scoped, paginated).
+POST /api/users – Create a user (requires permission).
+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.
+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 })
+);
+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
+
+curl -X POST http://localhost:3000/api/auth/register \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"a@b.com","password":"Secret123!","tenantId":"t-001","name":"Alice"}'
+
+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.
+- 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 & refresh secrets periodically.
+Limit login attempts; log auth events for auditing.
+License
+Internal — Company proprietary.

package/SECURITY

@@ -0,0 +1,31 @@
+# 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

@@ -0,0 +1,100 @@
+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/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@ciscode/authentication-kit",
+    "publishConfig": { "access": "public"},
+    "version": "1.0.33",
+    "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"
+    },
+    "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"
+    }
+}

package/src/config/db.config.js

@@ -0,0 +1,21 @@
+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;