soajs.controller 4.2.42 → 4.3.0

package/docs/multi-tenant-security.md

@@ -0,0 +1,183 @@
+# Multi-Tenant Security Pipeline
+
+The SOAJS Controller Gateway implements a comprehensive security pipeline for multi-tenant environments.
+
+## Security Check Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                         MULTI-TENANT SECURITY CHECKS                            │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+  Incoming Request with Key
+          │
+          ▼
+  ┌───────────────────┐
+  │ 1. IP Whitelist   │ Check application-level IP restrictions
+  │    Validation     │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 2. Geo-Location   │ Validate request origin geography
+  │    Check          │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 3. Device         │ Verify device fingerprint
+  │    Fingerprint    │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 4. ACL Check      │ Validate service/API access permission
+  │                   │ FAIL → 403 Forbidden
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 5. OAuth Check    │ Validate token (OAuth2 or JWT)
+  │                   │ FAIL → 401 Unauthorized
+  └─────────┬─────────┘
+            │ PASS
+            ▼
+  ┌───────────────────┐
+  │ 6. URAC Profile   │ Load user profile and groups
+  │    Resolution     │ Resolve user-specific ACL
+  └─────────┬─────────┘
+            │
+            ▼
+     Continue to Service
+```
+
+## Security Checks Detail
+
+### 1. IP Whitelist Validation
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates that the request IP is allowed to access the application.
+
+- Configured per external key in the key's `geo` field
+- Supports CIDR notation for IP ranges
+- Also supports gateway-level whitelist via custom registry
+
+### 2. Geo-Location Check
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates request origin based on geographic location.
+
+- Configured in external key's `geo` field
+- Supports country-level restrictions
+
+### 3. Device Fingerprint
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates device fingerprint for mobile/app authentication.
+
+- Configured in external key's `device` field
+- Useful for mobile app authentication
+
+### 4. ACL Check
+
+**Middleware:** `mw/mt/utils.js`
+
+Validates that the tenant has access to the requested service/API.
+
+ACL Resolution Priority:
+1. User-specific ACL (from URAC profile)
+2. Application ACL (from tenant application)
+3. Package ACL (from product package)
+
+### 5. OAuth Check
+
+**Middleware:** `mw/oauth/index.js`
+
+Validates OAuth2 tokens or JWT.
+
+- Supports OAuth2 password grant
+- Supports JWT validation
+- Configurable per service
+
+### 6. URAC Profile Resolution
+
+**Middleware:** `mw/mt/urac.js`
+
+Loads user profile from URAC for authenticated requests.
+
+- Resolves user groups
+- Applies user-specific ACL overrides
+- Handles network package override for user packages
+
+## IP Whitelist Configuration
+
+### Gateway-Level Whitelist
+
+```javascript
+// In custom registry: gateway.value.mt.whitelist
+{
+  "mt": {
+    "whitelist": {
+      "ips": ["10.0.0.0/8", "192.168.1.0/24"],
+      "acl": true,     // Skip ACL checks for whitelisted IPs
+      "oauth": true    // Skip OAuth checks for whitelisted IPs
+    }
+  }
+}
+```
+
+### Key-Level Restrictions
+
+```javascript
+// In external key definition
+{
+  "extKey": "...",
+  "env": "DEV",
+  "geo": {
+    "ips": ["192.168.1.0/24"],
+    "countries": ["US", "CA"]
+  },
+  "device": {
+    "allow": ["iOS", "Android"]
+  }
+}
+```
+
+## ACL Structure
+
+```javascript
+{
+  "serviceName": {
+    "version": {
+      "access": true,                        // or false, or ["group1", "group2"]
+      "apisPermission": "restricted",        // "restricted" = whitelist mode
+      "get": {
+        "apis": {
+          "/api/path": {
+            "access": ["owner", "admin"]     // Groups allowed
+          }
+        }
+      },
+      "post": { ... },
+      "put": { ... },
+      "delete": { ... }
+    }
+  }
+}
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 150 | ACL validation failed - no access to service |
+| 151 | ACL validation failed - no access to API |
+| 152 | ACL validation failed - version mismatch |
+| 153 | Geo-location validation failed |
+| 154 | Device validation failed |
+| 155 | IP whitelist validation failed |
+| 401 | OAuth token invalid or expired |
+| 403 | Access forbidden |

package/docs/request-flow.md

@@ -0,0 +1,230 @@
+# Request Flow
+
+The complete request lifecycle through the SOAJS Controller Gateway.
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────┐
+│                              REQUEST LIFECYCLE                                   │
+└──────────────────────────────────────────────────────────────────────────────────┘
+
+  HTTP Request                                                      HTTP Response
+       │                                                                  ▲
+       ▼                                                                  │
+┌──────────────┐                                                   ┌──────────────┐
+│ 1. SOAJS MW  │ Initialize req.soajs context                      │ Error Handler│
+│              │ Attach registry reference                         │              │
+└──────┬───────┘                                                   └──────▲───────┘
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 2. Security  │ CORS, IP Ban, Maintenance Mode                           │
+│    Checks    │                                                          │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 3. URL Parse │ Extract: serviceName, version, path                      │
+│              │ Extract: key/token from header/query                     │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 4. Service   │ Resolve service host via awareness                       │
+│   Discovery  │ Support HA (K8s/Swarm) or custom                         │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 5. Tenant    │ Load key data, validate tenant                           │
+│   Resolution │ Extract ACL from package                                 │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 6. Security  │ IP Whitelist → Geo Check → Device Check                  │
+│   Pipeline   │ → ACL Check → OAuth Check                                │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────┐                                                          │
+│ 7. Traffic   │ Rate limiting with configurable                          │
+│   Control    │ strategies and storage backends                          │
+└──────┬───────┘                                                          │
+       │                                                                  │
+       ▼                                                                  │
+┌──────────────────────────────────────────────────────────────────┬──────┘
+│ 8. PROXY TO SERVICE                                              │
+│                                                                  │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐  │
+│  │  Resolve Host   │───▶│  Build Request  │───▶│  HTTP Proxy  │  │
+│  │  (awareness)    │    │  (headers/body) │    │  (forward)   │  │
+│  └─────────────────┘    └─────────────────┘    └──────────────┘  │
+│                                                       │          │
+│                                                       ▼          │
+│                                            ┌──────────────────┐  │
+│                                            │  Target Service  │  │
+│                                            │  (Microservice)  │  │
+│                                            └──────────────────┘  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+## Stage Details
+
+### 1. SOAJS Initialization
+
+**Middleware:** `mw/soajs/index.js`
+
+- Creates `req.soajs` object
+- Attaches registry reference
+- Sets up logging context
+- Initializes controller params
+
+### 2. Security Checks
+
+**Middlewares:** `mw/cors`, `mw/ip2ban`, `mw/maintenanceMode`
+
+- CORS preflight handling
+- IP blacklist enforcement
+- Maintenance mode check
+
+### 3. URL Parsing
+
+**Middleware:** `mw/url/index.js`
+
+- Extracts service name from URL path
+- Parses version number (if provided)
+- Extracts API path
+
+### 4. Service Discovery
+
+**Middleware:** `mw/awareness/index.js`
+
+- Attaches `getHost()` and `getLatestVersion()` functions
+- Supports both custom and HA modes
+
+### 5. Tenant Resolution
+
+**Middlewares:** `mw/key`, `mw/keyACL`
+
+- Loads external key data
+- Validates key for environment
+- Extracts ACL from package or application
+
+### 6. Security Pipeline
+
+**Middleware:** `mw/mt/index.js`
+
+- IP whitelist validation
+- Geo-location checks
+- Device fingerprint verification
+- ACL enforcement
+- OAuth token validation
+
+### 7. Traffic Control
+
+**Middleware:** `mw/traffic/index.js`
+
+- Rate limiting per strategy
+- Response headers (X-RateLimit-*)
+
+### 8. Proxy to Service
+
+**Middleware:** `mw/gotoService/*`
+
+- Resolves target host
+- Builds proxy request
+- Forwards to microservice
+- Returns response to client
+
+## Configuration Model
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           CONFIGURATION HIERARCHY                               │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                    ENVIRONMENT VARIABLES (Highest Priority)             │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  SOAJS_ENV              │  Environment code (default: "dev")            │
+    │  SOAJS_SOLO             │  Solo mode flag (local registry)              │
+    │  SOAJS_DEPLOY_HA        │  HA mode: "kubernetes" | "swarm"              │
+    │  SOAJS_MAX_BODY_SIZE    │  Max request body (default: 10MB)             │
+    │  SOAJS_SENSITIVE_ENVS   │  Sensitive env codes (default: ["dashboard"]) │
+    └─────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                         SERVICE CONFIGURATION                           │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  config.js              │  Service metadata (name, version, port)       │
+    │  profiles/single.js     │  MongoDB connection profile                   │
+    │  profiles/solo.js       │  Local file-based profile                     │
+    └─────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                       REGISTRY (from Core DB)                           │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  services               │  Service definitions (ports, hosts, versions) │
+    │  serviceConfig          │  Global configs (throttling, CORS, OAuth)     │
+    │  custom.gateway         │  Gateway-specific settings                    │
+    │  dbs                    │  Database connection configs                  │
+    └─────────────────────────────────────────────────────────────────────────┘
+                                        │
+                                        ▼
+    ┌─────────────────────────────────────────────────────────────────────────┐
+    │                      TENANT/APPLICATION (Lowest Priority)               │
+    ├─────────────────────────────────────────────────────────────────────────┤
+    │  Tenant.application     │  App-specific OAuth, ACL overrides            │
+    │  Package.acl            │  Package-level access control                 │
+    └─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Rate Limiting Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           RATE LIMITING (THROTTLING)                            │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         STRATEGY SELECTION                                 │
+    │                                                                            │
+    │   ┌─────────────────────────┐        ┌─────────────────────────┐           │
+    │   │   publicAPIStrategy     │        │   privateAPIStrategy    │           │
+    │   │   (Unauthenticated)     │        │   (Authenticated)       │           │
+    │   └───────────┬─────────────┘        └───────────┬─────────────┘           │
+    │               │                                  │                         │
+    │               └──────────────┬───────────────────┘                         │
+    │                              ▼                                             │
+    └──────────────────────────────┬─────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         CONFIGURATION CASCADE                              │
+    │                                                                            │
+    │   1. Service-specific: gateway.throttling                                  │
+    │   2. Custom registry: gateway.value.traffic.throttling                     │
+    │   3. Global default: serviceConfig.throttling                              │
+    └──────────────────────────────┬─────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         STORAGE BACKENDS                                   │
+    │                                                                            │
+    │   ┌─────────────────────────┐        ┌─────────────────────────┐           │
+    │   │       Memory            │        │       MongoDB           │           │
+    │   │   (Fast, volatile)      │        │   (Persistent, shared)  │           │
+    │   └─────────────────────────┘        └─────────────────────────┘           │
+    └──────────────────────────────┬─────────────────────────────────────────────┘
+                                   │
+                                   ▼
+    ┌────────────────────────────────────────────────────────────────────────────┐
+    │                         RESPONSE HEADERS                                   │
+    │                                                                            │
+    │   X-RateLimit-Limit      │  Maximum requests allowed                       │
+    │   X-RateLimit-Remaining  │  Requests remaining in window                   │
+    │   Retry-After            │  Seconds until window resets                    │
+    └────────────────────────────────────────────────────────────────────────────┘
+```

package/docs/service-discovery.md

@@ -0,0 +1,167 @@
+# Service Discovery Modes
+
+The SOAJS Controller Gateway supports two service discovery modes: Custom (non-Kubernetes) and HA (Kubernetes/Docker Swarm).
+
+## Discovery Modes Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                           SERVICE DISCOVERY MODES                               │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────┐    ┌──────────────────────────────────────────┐
+│        CUSTOM MODE              │    │            HA MODE                       │
+│      (Non-Kubernetes)           │    │     (Kubernetes / Docker Swarm)          │
+├─────────────────────────────────┤    ├──────────────────────────────────────────┤
+│                                 │    │                                          │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │      Registry DB        │    │    │  │        Cluster API               │    │
+│  │   (MongoDB/Local)       │    │    │  │    (K8s API / Docker API)        │    │
+│  └───────────┬─────────────┘    │    │  └────────────────┬─────────────────┘    │
+│              │                  │    │                   │                      │
+│              ▼                  │    │                   ▼                      │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │   Static Host List      │    │    │  │    Dynamic Service Discovery     │    │
+│  │   per Service/Version   │    │    │  │    via Labels/Selectors          │    │
+│  └───────────┬─────────────┘    │    │  └────────────────┬─────────────────┘    │
+│              │                  │    │                   │                      │
+│              ▼                  │    │                   ▼                      │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │   In-Memory Health      │    │    │  │   Automatic Health Monitoring    │    │
+│  │   State Tracking        │    │    │  │   via Pod/Container Status       │    │
+│  └───────────┬─────────────┘    │    │  └────────────────┬─────────────────┘    │
+│              │                  │    │                   │                      │
+│              ▼                  │    │                   ▼                      │
+│  ┌─────────────────────────┐    │    │  ┌──────────────────────────────────┐    │
+│  │   Round-Robin           │    │    │  │   Cluster Load Balancing         │    │
+│  │   Selection             │    │    │  │   (via Service/Ingress)          │    │
+│  └─────────────────────────┘    │    │  └──────────────────────────────────┘    │
+│                                 │    │                                          │
+└─────────────────────────────────┘    └──────────────────────────────────────────┘
+```
+
+## Custom Mode
+
+Used when running outside of container orchestration platforms.
+
+### Configuration
+
+Set via environment variable:
+```bash
+# Do not set SOAJS_DEPLOY_HA, or set it to empty
+unset SOAJS_DEPLOY_HA
+```
+
+### How it Works
+
+1. **Registry Loading**: Service hosts are loaded from MongoDB registry
+2. **Host List**: Static list of hosts per service/version
+3. **Health Tracking**: In-memory state tracking with heartbeat
+4. **Load Balancing**: Round-robin selection among healthy hosts
+
+### Registry Structure
+
+```javascript
+// In environment registry
+{
+  "services": {
+    "oauth": {
+      "port": 4002,
+      "hosts": {
+        "1": ["host1.local", "host2.local"],
+        "2": ["host3.local"]
+      }
+    }
+  }
+}
+```
+
+## HA Mode (Kubernetes)
+
+Used when running in Kubernetes.
+
+### Configuration
+
+```bash
+export SOAJS_DEPLOY_HA=kubernetes
+```
+
+### How it Works
+
+1. **API Discovery**: Uses Kubernetes API to discover services
+2. **Label Selectors**: Finds pods via SOAJS labels
+3. **Health Monitoring**: Leverages pod readiness/liveness probes
+4. **Load Balancing**: Can use Kubernetes Service or direct pod access
+
+### Kubernetes Labels
+
+SOAJS uses these labels to discover services:
+
+```yaml
+metadata:
+  labels:
+    soajs.env.code: dev
+    soajs.service.name: oauth
+    soajs.service.version: "1"
+```
+
+## HA Mode (Docker Swarm)
+
+Used when running in Docker Swarm.
+
+### Configuration
+
+```bash
+export SOAJS_DEPLOY_HA=swarm
+```
+
+### How it Works
+
+1. **API Discovery**: Uses Docker Swarm API to discover services
+2. **Label Selectors**: Finds tasks via SOAJS labels
+3. **Health Monitoring**: Leverages task health checks
+4. **Load Balancing**: Can use Swarm service mesh or direct task access
+
+## Awareness Middleware
+
+**File:** `mw/awareness/index.js`
+
+The awareness middleware attaches helper functions to the request:
+
+```javascript
+req.soajs.awareness = {
+  getHost: function(serviceName, version, callback) {
+    // Returns host:port for the service
+  },
+  getLatestVersion: function(serviceName, callback) {
+    // Returns latest available version
+  }
+};
+```
+
+## Cross-Environment Awareness
+
+**File:** `mw/awarenessEnv/index.js`
+
+For roaming requests that need to access services in other environments:
+
+```javascript
+req.soajs.awarenessEnv = {
+  getHost: function(envCode, serviceName, version, callback) {
+    // Returns host:port for service in specified environment
+  }
+};
+```
+
+## Driver Module
+
+**File:** `modules/driver/index.js`
+
+The driver module abstracts infrastructure-specific operations:
+
+| Method | Description |
+|--------|-------------|
+| `getServiceHosts()` | Get all hosts for a service |
+| `getServiceHost()` | Get a single host (load balanced) |
+| `getLatestVersion()` | Get latest version number |
+| `getInfo()` | Get node/container info |

package/mw/key/index.js

@@ -8,13 +8,15 @@
  * found in the LICENSE file at the root of this repository
  */
 
+const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
+
 /**
  *
  * @param {object} configuration {provision,regEnvironment}
  * @returns {Function}
  */
 module.exports = (configuration) => {
-	
+
 	return (req, res, next) => {
 		let key = req.get("key");
 		if (key) {
@@ -34,6 +36,19 @@ module.exports = (configuration) => {
 							return next(144);
 						}
 					}
+
+					// Check for network-based package override
+					let network = get(["soajs", "registry", "custom", "gateway", "value", "lastSeen", "network"], req);
+					if (network) {
+						let product = keyObj.application.product;
+						let networkPackageConfig = get(["config", "gateway", "networkPackages", network, product], keyObj);
+						if (networkPackageConfig && networkPackageConfig.default) {
+							let originalPackage = keyObj.application.package;
+							keyObj.application.package = networkPackageConfig.default;
+							req.soajs.log.debug("Network package override: replaced package [" + originalPackage + "] with [" + networkPackageConfig.default + "] for network [" + network + "] and product [" + product + "]");
+						}
+					}
+
 					configuration.provision.getPackageData(keyObj.application.package, function (err, packObj) {
 						if (err) {
 							req.soajs.log.error("Unable to fetch data about package [" + keyObj.application.package + "]");

package/mw/mt/urac.js

@@ -14,6 +14,8 @@ let provision = coreModules.provision;
 
 const lib = require("./lib.js");
 
+const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
+
 function Urac(param) {
 	let _self = this;
 
@@ -101,7 +103,25 @@ Urac.prototype.resolveACL = function (cb) {
 		let productCode = _self.soajs.tenant.application.product;
 		if (_self.userRecord.groupsConfig && _self.userRecord.groupsConfig.allowedPackages) {
 			if (_self.userRecord.groupsConfig.allowedPackages[productCode]) {
-				provision.getPackagesData(_self.userRecord.groupsConfig.allowedPackages[productCode], (error, arrayACLs) => {
+				let allowedPackages = _self.userRecord.groupsConfig.allowedPackages[productCode].slice();
+
+				// Check for user-specific network package override
+				let network = get(["registry", "custom", "gateway", "value", "lastSeen", "network"], _self.soajs);
+				if (network) {
+					let keyObj = get(["controller", "serviceParams", "keyObj"], _self.soajs);
+					let networkPackageConfig = get(["config", "gateway", "networkPackages", network, productCode], keyObj);
+					if (networkPackageConfig && networkPackageConfig.users) {
+						for (let i = 0; i < allowedPackages.length; i++) {
+							if (networkPackageConfig.users[allowedPackages[i]]) {
+								let originalPackage = allowedPackages[i];
+								allowedPackages[i] = networkPackageConfig.users[allowedPackages[i]];
+								_self.soajs.log.debug("User network package override: replaced package [" + originalPackage + "] with [" + allowedPackages[i] + "] for network [" + network + "] and product [" + productCode + "]");
+							}
+						}
+					}
+				}
+
+				provision.getPackagesData(allowedPackages, (error, arrayACLs) => {
 					if (error) {
 						return cb();
 					} else {

package/mw/mt/utils.js

@@ -632,6 +632,8 @@ let utils = {
 					obj.req.soajs.log.error(error.message, error.code);
 					return cb(146);
 				}
+				//NOTE: if the user changes the account's email or phone and validateTokenAccount is set to true,
+				// 		kick the user out to force re login. i.e. the username behaviour is similar by default
 				if (obj.keyObj.config && obj.keyObj.config.gateway && obj.keyObj.config.gateway.validateTokenAccount) {
 					if (obj.req.soajs.uracDriver.bearerTokenUser && record) {
 						if (obj.keyObj.config.gateway.validateTokenAccount.email && record.email) {