soajs.controller 4.2.43 → 4.3.1

package/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
 
     services:
       mongodb:
-        image: mongo:6
+        image: mongo:8
         ports:
           - 27017:27017
 
@@ -23,7 +23,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
 
       - name: Install dependencies
         run: npm install

package/.github/workflows/release.yml

@@ -2,7 +2,9 @@ name: Release
 
 on:
   push:
-    branches: [ release, release/* ]
+    branches:
+      - release
+      - 'release/**'
 
 jobs:
   test:
@@ -10,7 +12,7 @@ jobs:
 
     services:
       mongodb:
-        image: mongo:6
+        image: mongo:8
         ports:
           - 27017:27017
 
@@ -21,7 +23,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
 
       - name: Install dependencies
         run: npm install

package/docs/middleware/mt.md

@@ -82,13 +82,393 @@ The MT middleware handles multi-tenant security checks, URAC integration, and pr
 | 1 | `ipWhitelist` | Validates IP against whitelist |
 | 2 | `securityGeoCheck` | Validates geographic location |
 | 3 | `securityDeviceCheck` | Validates device fingerprint |
-| 4 | `aclCheck` | Validates service-level ACL |
+| 4 | `aclCheck` | Loads service-level ACL |
 | 5 | `oauthCheck` | Validates OAuth token (if required) |
 | 6 | `uracCheck` | Loads user profile from URAC |
-| 7 | `aclUrackCheck` | Validates user-specific ACL |
+| 7 | `aclUrackCheck` | Overrides ACL with user-specific ACL |
 | 8 | `serviceCheck` | Validates service access |
 | 9 | `apiCheck` | Validates API access |
 
+---
+
+## Waterfall Check Details
+
+### 1. ipWhitelist
+
+**Purpose:** Check if the client IP is in a trusted whitelist, optionally bypassing ACL and OAuth checks.
+
+**Location:** `mw/mt/utils.js:166`
+
+**Configuration:** `registry.custom.gateway.value.mt.whitelist`
+
+```javascript
+{
+  "mt": {
+    "whitelist": {
+      "ips": ["10.0.0.0/8", "192.168.1.0/24", "127.0.0.1"],
+      "acl": true,    // Skip ACL checks for whitelisted IPs
+      "oauth": true   // Skip OAuth checks for whitelisted IPs
+    }
+  }
+}
+```
+
+**Behavior:**
+- Uses CIDR notation (Netmask) for IP range matching
+- Sets `obj.skipACL = true` if `whitelist.acl` is enabled and IP matches
+- Sets `obj.skipOAUTH = true` if `whitelist.oauth` is enabled and IP matches
+- Netmask objects are cached for performance
+
+**Use Cases:**
+- Trusted internal services calling the gateway
+- Development/testing environments
+- Load balancer health checks
+
+---
+
+### 2. securityGeoCheck
+
+**Purpose:** Validates the client IP against geographic allow/deny lists configured on the tenant key.
+
+**Location:** `mw/mt/utils.js:309`
+
+**Configuration:** `keyObj.geo`
+
+```javascript
+{
+  "geo": {
+    "allow": ["10.0.0.0/8", "192.168.0.0/16"],  // Only these IPs allowed
+    "deny": ["10.0.1.0/24"]                      // Block these IPs
+  }
+}
+```
+
+**Behavior:**
+- **Deny list checked first:** If client IP matches any deny entry → Error 155
+- **Allow list checked second:** If allow list exists and IP doesn't match → Error 155
+- Uses CIDR notation for IP range matching
+- Skipped if `obj.skipACL = true` (from ipWhitelist)
+
+**Error Codes:**
+| Code | Description |
+|------|-------------|
+| 155 | Geographic access denied |
+
+---
+
+### 3. securityDeviceCheck
+
+**Purpose:** Validates the client device/browser against allow/deny lists configured on the tenant key.
+
+**Location:** `mw/mt/utils.js:355`
+
+**Configuration:** `keyObj.device`
+
+```javascript
+{
+  "device": {
+    "allow": [
+      { "family": "Chrome" },
+      { "family": "Firefox", "major": { "min": "90" } },
+      { "family": "Safari", "os": { "family": "Mac OS X" } }
+    ],
+    "deny": [
+      { "family": "IE" },
+      { "family": "Chrome", "major": { "max": "80" } }
+    ]
+  }
+}
+```
+
+**Validation Fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `family` | string | Browser family (Chrome, Firefox, Safari, IE, etc.) |
+| `major` | string/object | Major version. Object: `{ "min": "90", "max": "100" }` |
+| `minor` | string/object | Minor version |
+| `patch` | string/object | Patch version |
+| `os.family` | string | OS family (Windows, Mac OS X, Linux, etc.) |
+| `os.major` | string/object | OS major version |
+
+**Behavior:**
+- Uses `useragent` library to parse User-Agent header
+- **Deny list checked first:** If device matches any deny entry → Error 156
+- **Allow list checked second:** If allow list exists and device doesn't match → Error 156
+- Wildcard `"*"` matches any value
+- Skipped if `obj.skipACL = true` (from ipWhitelist)
+
+**Error Codes:**
+| Code | Description |
+|------|-------------|
+| 156 | Device access denied |
+
+---
+
+### 4. aclCheck
+
+**Purpose:** Loads the pre-computed ACL from `serviceParams.finalAcl` into the waterfall object.
+
+**Location:** `mw/mt/utils.js:274`
+
+**Behavior:**
+- Simple passthrough that loads `obj.req.soajs.controller.serviceParams.finalAcl` into `obj.finalAcl`
+- The ACL was computed earlier in the [keyACL middleware](./keyACL.md)
+- This ACL will be used by subsequent checks (serviceCheck, apiCheck)
+
+---
+
+### 5. oauthCheck
+
+**Purpose:** Validates OAuth access tokens for private APIs and handles PIN-locked sessions.
+
+**Location:** `mw/mt/utils.js:463`
+
+**Prerequisites:**
+- `serviceParam.oauth = true` must be set on the service
+- Skipped if `obj.skipOAUTH = true` (from ipWhitelist)
+
+**Public vs Private API Detection:**
+| Scenario | ACL Configuration | Result |
+|----------|-------------------|--------|
+| No access restriction | `access: false` or missing | Public |
+| Service restricted, API public | `access: true`, `apis[path].access: false` | Public |
+| Restricted permission, API public | `apisPermission: "restricted"`, `apis[path].access: false` | Public |
+| Any access restriction | `access: true` or `apis[path].access: true` | Private |
+
+**PIN Login Support:**
+
+PIN login is a two-factor authentication mechanism where users must enter a PIN after OAuth login.
+
+**Configuration:** `registry.custom.oauth.value`
+
+```javascript
+{
+  "oauth": {
+    "value": {
+      "pinWrapper": {
+        "servicename": "custom-service",
+        "apiname": "/verify-pin"
+      },
+      "pinWhitelist": {
+        "servicename": {
+          "get": {
+            "apis": ["/public-api"],
+            "regex": ["/user/:id/profile"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**PIN Flow:**
+1. User logs in with OAuth → receives token with `pinLocked: true`
+2. Most APIs blocked (error 145) until PIN verified
+3. PIN whitelist allows specific APIs before verification
+4. After PIN verification, `pinLogin: true` set, full access granted
+
+**Error Codes:**
+| Code | Description |
+|------|-------------|
+| 145 | PIN verification required |
+
+---
+
+### 6. uracCheck
+
+**Purpose:** Initializes the URAC driver to load user profile, groups, ACL, and configuration.
+
+**Location:** `mw/mt/utils.js:624`
+
+**Behavior:**
+- Skipped if `obj.skipOAUTH = true` or no bearer token present
+- Creates `req.soajs.uracDriver` instance
+- Handles **roaming** across environments (e.g., dashboard token used in dev environment)
+
+**Roaming Support:**
+
+Roaming allows users authenticated in a "sensitive" environment (default: `dashboard`) to access other environments.
+
+**Configuration:** Environment variable `SOAJS_SENSITIVE_ENVS`
+```bash
+SOAJS_SENSITIVE_ENVS='["dashboard", "production"]'
+```
+
+**Roaming Flow:**
+1. Check if token's environment is in sensitive list AND differs from current
+2. Load tenant data for the token's client ID
+3. Load registry for the token's environment
+4. Set `req.soajs.tenant.roaming` with cross-environment context
+
+**Token Account Validation:**
+
+Validates that user account hasn't changed since token was issued.
+
+**Configuration:** `keyObj.config.gateway.validateTokenAccount`
+
+```javascript
+{
+  "gateway": {
+    "validateTokenAccount": {
+      "email": true,   // Invalidate if email changed
+      "phone": true    // Invalidate if phone changed
+    }
+  }
+}
+```
+
+**Error Codes:**
+| Code | Description |
+|------|-------------|
+| 146 | User profile not found or account changed |
+| 170 | Roaming context failed to load |
+
+---
+
+### 7. aclUrackCheck
+
+**Purpose:** Overrides the tenant/package ACL with user-specific ACL from URAC profile.
+
+**Location:** `mw/mt/utils.js:217`
+
+**Behavior:**
+- Skipped if `obj.skipOAUTH = true` or no URAC driver
+- Retrieves user's personal ACL via `uracDriver.getAcl()`
+- If user ACL exists, it **replaces** the tenant/package ACL
+- Handles version resolution when no version requested
+- Processes method-specific ACL (GET, POST, etc.)
+
+**ACL Structure:**
+```javascript
+// User ACL from URAC
+{
+  "servicename": {
+    "1": {                              // Version
+      "access": true,
+      "get": {
+        "apis": { "/endpoint": { "access": true } },
+        "apisRegExp": [...],
+        "apisPermission": "restricted"
+      },
+      "post": { ... }
+    }
+  }
+}
+```
+
+**Version Resolution:**
+- If request doesn't specify version, finds latest version in user's ACL
+- Uses `coreLibs.version.getLatest()` for semantic version comparison
+
+---
+
+### 8. serviceCheck
+
+**Purpose:** Validates that the tenant/user has access to the requested service.
+
+**Location:** `mw/mt/utils.js:289`
+
+**Behavior:**
+- Skipped if `obj.skipACL = true` (from ipWhitelist)
+- Checks if `obj.finalAcl` exists for the service
+- If no ACL found → Error 154 (service not accessible)
+
+**Error Codes:**
+| Code | Description |
+|------|-------------|
+| 154 | Service not accessible |
+
+---
+
+### 9. apiCheck
+
+**Purpose:** Validates access to the specific API endpoint based on ACL configuration.
+
+**Location:** `mw/mt/utils.js:748`
+
+**Behavior:**
+- Skipped if `obj.skipACL = true` (from ipWhitelist)
+- Matches API path against `apis` (exact match) or `apisRegExp` (pattern match)
+- Sets `isAPIPublic = true` for traffic middleware throttling strategy
+
+**API Matching Order:**
+1. Exact match in `system.apis[path]`
+2. RegExp match in `system.apisRegExp[]`
+
+**Access Control Logic:**
+
+| ACL Configuration | User State | Result |
+|-------------------|------------|--------|
+| `access: false` | Any | Public API, allowed |
+| `access: true`, no user | - | Error 158 |
+| `access: true`, user logged in | - | Check group permissions |
+| `access: ["group1", "group2"]` | User in group | Allowed |
+| `access: ["group1"]` | User not in group | Error 157/160 |
+| `apisPermission: "restricted"` | API not in list | Error 159 |
+
+**Error Codes:**
+| Code | Description |
+|------|-------------|
+| 157 | User not in required access group |
+| 158 | Login required |
+| 159 | API not found (restricted mode) |
+| 160 | User lacks required group membership |
+| 161 | API requires login but user not authenticated |
+
+---
+
+## Waterfall Execution Flow
+
+```
+┌─────────────────┐
+│  ipWhitelist    │──▶ Sets skipACL, skipOAUTH flags
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ securityGeoCheck│──▶ Error 155 if geo-blocked
+└────────┬────────┘    (skipped if skipACL)
+         │
+         ▼
+┌─────────────────┐
+│securityDeviceChk│──▶ Error 156 if device blocked
+└────────┬────────┘    (skipped if skipACL)
+         │
+         ▼
+┌─────────────────┐
+│   aclCheck      │──▶ Loads finalAcl from keyACL middleware
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  oauthCheck     │──▶ Error 145 if PIN required
+└────────┬────────┘    (skipped if skipOAUTH or public API)
+         │
+         ▼
+┌─────────────────┐
+│   uracCheck     │──▶ Error 146/170 if user load fails
+└────────┬────────┘    (skipped if skipOAUTH)
+         │
+         ▼
+┌─────────────────┐
+│ aclUrackCheck   │──▶ Overrides ACL with user ACL
+└────────┬────────┘    (skipped if skipOAUTH)
+         │
+         ▼
+┌─────────────────┐
+│  serviceCheck   │──▶ Error 154 if no service ACL
+└────────┬────────┘    (skipped if skipACL)
+         │
+         ▼
+┌─────────────────┐
+│   apiCheck      │──▶ Error 157-161 if access denied
+└────────┬────────┘    (skipped if skipACL)
+         │
+         ▼
+     Success
+```
+
 ## Injection Object Structure
 
 The `soajsinjectobj` header contains:

package/mw/lastSeen/index.js

@@ -9,8 +9,131 @@
  */
 
 const { httpRequest } = require("../../lib/request.js");
+const { pathToRegexp } = require("path-to-regexp");
 const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
 
+// Cache compiled RegExp objects for route pattern matching
+const regexpCache = new Map();
+const MAX_REGEXP_CACHE_SIZE = 100;
+
+/**
+ * Check if a route pattern contains path parameters
+ * @param {string} route - The route pattern
+ * @returns {boolean}
+ */
+function hasPathParams(route) {
+    return route.includes("/:");
+}
+
+/**
+ * Get or create a cached RegExp for a route pattern
+ * @param {string} route - The route pattern
+ * @returns {RegExp}
+ */
+function getRouteRegExp(route) {
+    if (regexpCache.has(route)) {
+        return regexpCache.get(route);
+    }
+
+    let out = pathToRegexp(route, { sensitive: true });
+    let regexp = out.regexp || out;
+
+    // Simple LRU: clear oldest entries when cache is full
+    if (regexpCache.size >= MAX_REGEXP_CACHE_SIZE) {
+        const keysToDelete = Array.from(regexpCache.keys()).slice(0, Math.floor(MAX_REGEXP_CACHE_SIZE * 0.25));
+        keysToDelete.forEach(key => regexpCache.delete(key));
+    }
+
+    regexpCache.set(route, regexp);
+    return regexp;
+}
+
+/**
+ * Check if the current request should trigger lastSeen
+ * @param {Object} include - The include whitelist configuration
+ * @param {string} serviceName - The current service name
+ * @param {string} apiPath - The current API path
+ * @param {string} method - The HTTP method (GET, POST, etc.)
+ * @returns {boolean} - true if lastSeen should be triggered
+ */
+function shouldTriggerLastSeen(include, serviceName, apiPath, method) {
+    // No include filter = trigger for all (backward compatible)
+    if (!include) {
+        return true;
+    }
+
+    // Service not in whitelist
+    if (!include[serviceName]) {
+        return false;
+    }
+
+    const serviceConfig = include[serviceName];
+
+    // Service-level match (all APIs, all methods)
+    if (serviceConfig === true) {
+        return true;
+    }
+
+    // API-level match
+    if (typeof serviceConfig === 'object' && serviceConfig.apis) {
+        return isApiMethodMatch(serviceConfig.apis, apiPath, method);
+    }
+
+    return false;
+}
+
+/**
+ * Check if API path and method match the apis configuration
+ * @param {Object} apis - The apis configuration object
+ * @param {string} apiPath - The current API path
+ * @param {string} method - The HTTP method
+ * @returns {boolean}
+ */
+function isApiMethodMatch(apis, apiPath, method) {
+    // Check for wildcard first
+    if (apis["*"]) {
+        return isMethodMatch(apis["*"], method);
+    }
+
+    // Check exact match first
+    if (apis[apiPath]) {
+        return isMethodMatch(apis[apiPath], method);
+    }
+
+    // Check pattern matching for routes with path params
+    for (const routePattern of Object.keys(apis)) {
+        if (hasPathParams(routePattern)) {
+            const regexp = getRouteRegExp(routePattern);
+            if (regexp.test(apiPath)) {
+                return isMethodMatch(apis[routePattern], method);
+            }
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Check if method matches the method configuration
+ * @param {boolean|Array} methodConfig - true for all methods, or array of methods
+ * @param {string} method - The HTTP method
+ * @returns {boolean}
+ */
+function isMethodMatch(methodConfig, method) {
+    // true = all methods
+    if (methodConfig === true) {
+        return true;
+    }
+
+    // Array of methods (case-insensitive)
+    if (Array.isArray(methodConfig)) {
+        const lowerMethod = method.toLowerCase();
+        return methodConfig.some(m => m.toLowerCase() === lowerMethod);
+    }
+
+    return false;
+}
+
 /**
  *
  * @param configuration
@@ -25,6 +148,16 @@ module.exports = () => {
             let lastSeen = get(["soajs", "registry", "custom", "gateway", "value", "lastSeen"], req);
             if (lastSeen && lastSeen.active) {
 
+                // Check include filter
+                let currentService = get(["soajs", "controller", "serviceParams", "name"], req);
+                let currentApi = get(["soajs", "controller", "serviceParams", "parsedUrl", "pathname"], req);
+                let currentMethod = req.method;
+
+                if (!shouldTriggerLastSeen(lastSeen.include, currentService, currentApi, currentMethod)) {
+                    req.soajs.log.debug("lastSeen skipped for [" + currentService + " " + currentMethod + " " + currentApi + "]");
+                    return;
+                }
+
                 const item = {
                     "name": lastSeen.serviceName || "urac",
                     "version": lastSeen.serviceVersion || "3",
@@ -62,49 +195,7 @@ module.exports = () => {
                                     } else {
                                         req.soajs.log.debug("lastSeen ", body);
                                     }
-                                    // else if (!body.result) {
-                                    //     let errorMsg = "";
-                                    //     if (body.errors && body.errors && body.errors.details && body.errors.details.length > 0) {
-                                    //         body.errors.details.forEach((detail) => {
-                                    //             if (errorMsg === "") {
-                                    //                 errorMsg += detail.message;
-                                    //             }
-                                    //             else {
-                                    //                 errorMsg += " - " + detail.message;
-                                    //             }
-                                    //         });
-                                    //     }
-                                    //     req.soajs.log.debug("lastSeen", errorMsg);
-                                    // }
                                 });
-
-                            // let options = {
-                            //     method: "post",
-                            //     uri: "http://" + item.host + ":" + item.port + item.api,
-                            //     json: true
-                            // };
-                            // if (req.headers && req.headers.soajsinjectobj) {
-                            //     options.headers = { "soajsinjectobj": req.headers.soajsinjectobj };
-                            // }
-                            // request(options, (error, response, body) => {
-                            //     if (error) {
-                            //         req.soajs.log.debug("lastSeen failed for [" + item.name + "@" + item.version + " " + item.api + "]");
-                            //         req.soajs.log.debug("lastSeen " + error.message);
-                            //     } else if (!body.result) {
-                            //         let errorMsg = "";
-                            //         if (body.errors && body.errors && body.errors.details && body.errors.details.length > 0) {
-                            //             body.errors.details.forEach((detail) => {
-                            //                 if (errorMsg === "") {
-                            //                     errorMsg += detail.message;
-                            //                 }
-                            //                 else {
-                            //                     errorMsg += " - " + detail.message;
-                            //                 }
-                            //             });
-                            //         }
-                            //         req.soajs.log.debug("lastSeen", errorMsg);
-                            //     }
-                            // });
                         } else {
                             req.soajs.log.debug("lastSeen failed with no host for [" + item.name + "@" + item.version + " " + item.api + "]");
                         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.2.43",
+  "version": "4.3.1",
   "author": {
     "name": "soajs team",
     "email": "team@soajs.org"
@@ -23,20 +23,20 @@
     "http-proxy": "1.18.1",
     "jsonwebtoken": "9.0.3",
     "kubernetes-client": "9.0.0",
-    "lodash": "4.17.21",
+    "lodash": "4.17.23",
     "merge": "2.1.1",
     "netmask": "2.0.2",
     "oauth2-server": "2.4.1",
     "path-to-regexp": "8.3.0",
-    "soajs.core.libs": "1.2.1",
-    "soajs.core.modules": "5.2.17",
-    "soajs.urac.driver": "3.2.14",
+    "soajs.core.libs": "1.2.2",
+    "soajs.core.modules": "5.2.18",
+    "soajs.urac.driver": "3.2.15",
     "useragent": "2.3.0"
   },
   "devDependencies": {
-    "@babel/core": "7.28.6",
-    "@babel/plugin-transform-runtime": "7.28.5",
-    "@babel/preset-env": "7.28.6",
+    "@babel/core": "7.29.0",
+    "@babel/plugin-transform-runtime": "7.29.0",
+    "@babel/preset-env": "7.29.0",
     "@babel/runtime": "7.28.6",
     "express": "5.2.1",
     "grunt": "1.6.1",
@@ -50,7 +50,7 @@
     "grunt-jsdoc": "2.4.1",
     "grunt-mocha-test": "0.13.3",
     "mocha": "11.7.5",
-    "nock": "14.0.10",
+    "nock": "14.0.11",
     "request": "2.88.2",
     "sinon": "21.0.1"
   }