soajs.controller 4.2.43 → 4.3.0

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.2.43",
+  "version": "4.3.0",
   "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"
   }