soajs.controller 4.3.6 → 4.3.9

package/docs/configuration-custom-registry.md

@@ -27,6 +27,8 @@ registry.custom
 │       │       └── [service]       # Service-specific settings
 │       ├── maintenanceMode         # Gateway maintenance mode
 │       ├── lastSeen                # User activity tracking
+│       ├── oauth
+│       │   └── deviceIdCheck       # Turn the deviceId check off
 │       └── gotoService
 │           ├── monitor             # Request monitoring config
 │           └── renewReqMonitorOff  # Disable timeout renewal
@@ -448,6 +450,37 @@ Whitelists specific APIs that can be accessed when a user is PIN-locked (during
 
 ---
 
+## 13. OAuth Device ID Check
+
+**Path:** `registry.custom.gateway.value.oauth.deviceIdCheck`
+
+**Middleware:** `mw/oauth/index.js`
+
+Turns off the deviceId check done when authorising an access token. The check matches
+`user.deviceId` on the access token record against the `device-id` header on every
+private API call, and denies with error 156 on mismatch.
+
+```javascript
+{
+  "oauth": {
+    "deviceIdCheck": false                   // Turn off the deviceId check
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `deviceIdCheck` | boolean | `true` | Set to `false` to turn the deviceId check off |
+
+Only the boolean `false` turns the check off. Any other value, and a missing or
+malformed entry, leaves it on.
+
+Note this is a `gateway` entry, not an `oauth` one. The `registry.custom.oauth.value.*`
+entries above are consumed by `mw/mt/utils.js` and `mw/gotoService/roaming.js`, this one
+is read by the oauth middleware itself.
+
+---
+
 ## Complete Configuration Example
 
 ```javascript
@@ -514,6 +547,9 @@ Whitelists specific APIs that can be accessed when a user is PIN-locked (during
       "api": "/user/last/seen",
       "network": "production"
     },
+    "oauth": {
+      "deviceIdCheck": false
+    },
     "gotoService": {
       "monitor": {
         "blacklist": ["soamonitor", "urac"]
@@ -565,6 +601,7 @@ Custom registry configurations are processed in this order:
 | 4 | gotoService/preRedirect | `gotoService.renewReqMonitorOff` |
 | 5 | gotoService/redirectToService | `gotoService.monitor` |
 | 6 | mt (security checks) | `mt.whitelist`, `oauth.value.pinWrapper`, `oauth.value.pinWhitelist` |
+| 6a | oauth (called from mt) | `oauth.deviceIdCheck` |
 | 7 | idempotency | `idempotency.model`, `idempotency.services.[name]` |
 | 8 | traffic | `traffic.model`, `traffic.throttling` |
 | 9 | cache | `cache.model`, `cache.defaultTTL`, `cache.services.[name]` |

package/docs/middleware/idempotency.md

@@ -59,6 +59,7 @@ The Idempotency middleware prevents duplicate write operations by tracking reque
 {
   "idempotency": {
     "model": "memory",                    // Storage: "memory" or "mongo"
+    "enforce": false,                     // Global default for enforcement (optional)
     "services": {                         // Service configurations
       "av": {                             // Service name
         "enabled": true,                  // Enable for this service
@@ -71,6 +72,7 @@ The Idempotency middleware prevents duplicate write operations by tracking reque
       },
       "payment": {
         "enabled": true,
+        "enforce": true,                  // Require Idempotency-Key on matched APIs
         "ttl": 120000,
         "apis": [
           "POST /charge",
@@ -85,10 +87,18 @@ The Idempotency middleware prevents duplicate write operations by tracking reque
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
+| `enforce` | boolean | `false` | Global default enforcement (overridden per service) |
 | `services.[name].enabled` | boolean | `false` | Enable idempotency for this service |
+| `services.[name].enforce` | boolean | *(global)* | Require `Idempotency-Key` on matched APIs; overrides the global `enforce`. If unset, falls back to the global default |
 | `services.[name].ttl` | number | `60000` | Key expiration time in milliseconds |
 | `services.[name].apis` | string[] | `[]` | API patterns to protect (e.g., `"POST /path"`) |
 
+## Enforcement
+
+By default, requests without an `Idempotency-Key` header pass through untouched (backwards compatible). When `enforce` is enabled, a matched, non-GET API **requires** the header — a missing key returns **428 Precondition Required** (code `182`).
+
+Resolution order: `services.[name].enforce` takes precedence when set to a boolean; otherwise the top-level `enforce` applies. Enforcement never affects GET requests, unconfigured/disabled services, or APIs outside the configured `apis` list.
+
 ## API Pattern Matching
 
 APIs are matched using `METHOD /path` format with support for path parameters:
@@ -181,6 +191,26 @@ Content-Type: application/json
 }
 ```
 
+### Enforced (Missing Key)
+
+Returned when the matched API has enforcement enabled and no `Idempotency-Key` header is provided.
+
+```
+HTTP/1.1 428 Precondition Required
+Content-Type: application/json
+
+{
+  "result": false,
+  "errors": {
+    "codes": [182],
+    "details": [{
+      "code": 182,
+      "message": "Idempotency-Key header is required for this API."
+    }]
+  }
+}
+```
+
 ## Key Structure
 
 ```javascript
@@ -198,6 +228,7 @@ Keys are isolated per tenant to prevent cross-tenant collisions.
 |------|-------------|-------------|
 | 180 | 400 | Invalid Idempotency-Key format (not UUID v4) |
 | 181 | 409 | Request with this key is still being processed |
+| 182 | 428 | Idempotency-Key header required (enforcement enabled) |
 
 ## Usage Notes
 

package/docs/middleware/oauth.md

@@ -60,9 +60,53 @@ Uses oauth2-server library for token validation.
   │    bearerToken: user,   │
   │    type: 2              │
   │  }                      │
-  └─────────────────────────┘
+  └────────┬────────────────┘
+           │
+           ▼
+  ┌─────────────────────────┐
+  │  deviceId check         │ token user.deviceId vs device-id header
+  └────────┬────────────────┘
+           │
+           ├─── Mismatch ──▶ Error 156
+           │
+           ▼
+       next()
 ```
 
+#### deviceId check
+
+The access token record carries `user.deviceId`, set at login from the `device-id`
+header and carried forward across refreshes. It is matched against the `device-id`
+header on every private API call. The check runs on the record `authorise()` already
+fetched, so it costs no extra database call.
+
+The agent cannot be used for this, mobile sends the build number in the user-agent
+(ie: `democav/142 CFNetwork/3826.400.120 Darwin/24.3.0`) which changes on every build.
+
+Tokens with no `deviceId` are not checked. This covers tokens created before deviceId
+was introduced and clients that do not send the header at all, both get checked once
+the client logs in again with the header. A client that sends `device-id` on login but
+omits it on API calls is denied, the header has to be sent consistently.
+
+This check is only available for type 2, a type 0 JWT carries no stored token record.
+
+##### Turning it off
+
+The check is on by default. To turn it off for an environment, set `deviceIdCheck` to
+`false` under the `gateway` custom registry entry:
+
+```json
+{
+  "oauth": {
+    "deviceIdCheck": false
+  }
+}
+```
+
+Read from `registry.custom.gateway.value.oauth.deviceIdCheck`. Only the boolean `false`
+turns it off, any other value leaves it on, so a missing or malformed entry keeps the
+check running.
+
 ### Type 0: JWT
 
 Uses jsonwebtoken library for JWT validation.
@@ -155,6 +199,7 @@ Default OAuth service configuration:
 | Code | Description |
 |------|-------------|
 | 143 | Invalid or missing JWT token |
+| 156 | Device forbidden, the deviceId on the token does not match the device-id header |
 | OAuth2Error | Various OAuth2 errors (invalid_token, expired, etc.) |
 
 ## Properties Set

package/mw/idempotency/index.js

@@ -62,11 +62,9 @@ module.exports = function (configuration) {
 	return (req, res, next) => {
 		const idempotencyKey = req.headers['idempotency-key'];
 
-		if (!idempotencyKey) {
-			return next();
-		}
-
-		if (!isValidUUIDv4(idempotencyKey)) {
+		// Validate format only when a key was actually provided. The decision on a
+		// missing key is deferred until we know whether the target API enforces it.
+		if (idempotencyKey && !isValidUUIDv4(idempotencyKey)) {
 			req.soajs.controllerResponse({
 				'status': 400,
 				'code': 180,
@@ -103,6 +101,22 @@ module.exports = function (configuration) {
 			return next();
 		}
 
+		// Request targets an idempotency-enabled and matched API. Resolve enforcement:
+		// service-level 'enforce' overrides the global default.
+		const enforce = (typeof serviceConfig.enforce === 'boolean') ? serviceConfig.enforce : (idempotencyConfig.enforce === true);
+
+		if (!idempotencyKey) {
+			if (enforce) {
+				req.soajs.controllerResponse({
+					'status': 428,
+					'code': 182,
+					'msg': 'Idempotency-Key header is required for this API.'
+				});
+				return;
+			}
+			return next();
+		}
+
 		const modelType = idempotencyConfig.model || 'memory';
 		if (!model[modelType]) {
 			configuration.log.warn('Idempotency: Unknown model [' + modelType + ']. It can only be [memory || mongo]');

package/mw/oauth/index.js

@@ -32,9 +32,57 @@ module.exports = (configuration) => {
 	});
 	
 	let jwt = require('jsonwebtoken');
-	
+
+	/**
+	 * The deviceId check is on unless it is explicitly turned off at the custom registry.
+	 * Anything other than false leaves it on.
+	 *
+	 * req.soajs.registry.custom.gateway.value.oauth
+	 * {
+		  "oauth": {
+			"deviceIdCheck": false
+		  }
+		}
+	 *
+	 * @param req
+	 * @returns {boolean} true when the check is turned on
+	 */
+	let deviceIdCheckOn = (req) => {
+		if (req.soajs.registry &&
+			req.soajs.registry.custom &&
+			req.soajs.registry.custom.gateway &&
+			req.soajs.registry.custom.gateway.value &&
+			req.soajs.registry.custom.gateway.value.oauth &&
+			req.soajs.registry.custom.gateway.value.oauth.deviceIdCheck === false) {
+			return false;
+		}
+		return true;
+	};
+
+	/**
+	 * Matches the deviceId on the access token record against the device-id header.
+	 *
+	 * NOTE: we cannot check for agent, mobile is sending the build number
+	 *       (ie: "democav/142 CFNetwork/3826.400.120 Darwin/24.3.0") which changes on every build.
+	 *       we check deviceId instead. tokens with no deviceId (created before deviceId was
+	 *       introduced, or by a client that does not send the header) are not checked, they get
+	 *       checked once the client logs in again.
+	 *
+	 * @param req
+	 * @returns {boolean} true when the request is allowed to proceed
+	 */
+	let deviceIdMatch = (req) => {
+		if (!deviceIdCheckOn(req)) {
+			return true;
+		}
+		if (!req.oauth || !req.oauth.bearerToken || !req.oauth.bearerToken.user || !req.oauth.bearerToken.user.deviceId) {
+			return true;
+		}
+		return req.oauth.bearerToken.user.deviceId === req.get('device-id');
+	};
+
 	return (req, res, next) => {
-		
+
 		let oauthType = 2;
 		let tenantOauth = req.soajs.tenantOauth;
 		if (tenantOauth && Object.hasOwnProperty.call(tenantOauth, 'type')) {
@@ -45,7 +93,18 @@ module.exports = (configuration) => {
 		
 		//0=oauth0, 2=oauth2
 		if (2 === oauthType) {
-			oauthObj.authorise()(req, res, next);
+			//NOTE: authorise() sets req.oauth.bearerToken to the token record it fetched from the
+			//		model, the deviceId check is done on it here to avoid fetching the token again.
+			oauthObj.authorise()(req, res, (error) => {
+				if (error) {
+					return next(error);
+				}
+				if (!deviceIdMatch(req)) {
+					req.soajs.log.debug("Access denied, deviceId mismatch [deviceId: " + req.get('device-id') + "]");
+					return next(156);
+				}
+				return next();
+			});
 		} else {
 			let algorithms = req.soajs.registry.serviceConfig.oauth.algorithms || ["HS256"];
 			let audience = req.soajs.registry.serviceConfig.oauth.audience || "";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.3.6",
+  "version": "4.3.9",
   "author": {
     "name": "soajs team",
     "email": "team@soajs.org"
@@ -29,7 +29,7 @@
     "oauth2-server": "2.4.1",
     "path-to-regexp": "8.4.0",
     "soajs.core.libs": "1.2.2",
-    "soajs.core.modules": "5.2.19",
+    "soajs.core.modules": "5.2.20",
     "soajs.urac.driver": "3.2.15",
     "useragent": "2.3.0"
   },

package/test/unit/mw/idempotency/index.js

@@ -30,6 +30,7 @@ describe("Unit test for: mw - idempotency", () => {
 		it("should call next() when no Idempotency-Key header", (done) => {
 			let req = {
 				headers: {},
+				method: 'POST',
 				soajs: {
 					tenant: { id: '123' },
 					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
@@ -313,6 +314,244 @@ describe("Unit test for: mw - idempotency", () => {
 		});
 	});
 
+	describe("enforcement", () => {
+		it("should return 428 when enforced and no key on matched API", (done) => {
+			let responseData = null;
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					},
+					controllerResponse: (data) => {
+						responseData = data;
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, () => {
+				assert.fail('Should not call next');
+			});
+			setTimeout(() => {
+				assert.notStrictEqual(responseData, null);
+				assert.strictEqual(responseData.status, 428);
+				assert.strictEqual(responseData.code, 182);
+				done();
+			}, 10);
+		});
+
+		it("should call next() when enforced and key is present", (done) => {
+			let req = {
+				headers: { 'idempotency-key': '550e8400-e29b-41d4-a716-446655440010' },
+				method: 'POST',
+				soajs: {
+					tenant: { id: 'tenant-enforce' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										model: 'memory',
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {
+				writeHead: function() { return this; },
+				write: function() { return true; },
+				end: function() {},
+				on: function() {}
+			};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should call next() when not enforced and no key (backwards compatible)", (done) => {
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should return 428 when global enforce is set and service has no override", (done) => {
+			let responseData = null;
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										enforce: true,
+										services: {
+											test: { enabled: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					},
+					controllerResponse: (data) => {
+						responseData = data;
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, () => {
+				assert.fail('Should not call next');
+			});
+			setTimeout(() => {
+				assert.notStrictEqual(responseData, null);
+				assert.strictEqual(responseData.status, 428);
+				assert.strictEqual(responseData.code, 182);
+				done();
+			}, 10);
+		});
+
+		it("should let service enforce=false override global enforce=true", (done) => {
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										enforce: true,
+										services: {
+											test: { enabled: true, enforce: false, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should not enforce on GET requests", (done) => {
+			let req = {
+				headers: {},
+				method: 'GET',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+
+		it("should not enforce when API is not in the configured list", (done) => {
+			let req = {
+				headers: {},
+				method: 'POST',
+				soajs: {
+					tenant: { id: '123' },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'other'] } },
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									idempotency: {
+										services: {
+											test: { enabled: true, enforce: true, ttl: 60000, apis: ['POST /test'] }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+			let res = {};
+			let functionMw = mw(mockConfig);
+			functionMw(req, res, (error) => {
+				assert.ifError(error);
+				done();
+			});
+		});
+	});
+
 	describe("UUID validation", () => {
 		it("should accept valid UUID v4", (done) => {
 			let req = {

package/test/unit/mw/oauth/index.js

@@ -99,3 +99,171 @@ describe("Unit test for: mw - oauth", () => {
         });
     });
 });
+
+describe("Unit test for: mw - oauth deviceId check", () => {
+
+    // builds a configuration whose model returns an access token carrying the given deviceId
+    let buildConfiguration = (deviceId) => {
+        let user = {"id": "1"};
+        if (deviceId !== undefined) {
+            user.deviceId = deviceId;
+        }
+        return {
+            "soajs": {
+                "param": {}
+            },
+            "serviceConfig": {
+                "oauth": {
+                    grants: ["password", "refresh_token"],
+                    debug: false,
+                    accessTokenLifetime: 7200,
+                    refreshTokenLifetime: 1209600
+                }
+            },
+            "model": {
+                "getAccessToken": (bearerToken, cb) => {
+                    return cb(null, {
+                        "token": bearerToken,
+                        "expires": new Date(new Date().getTime() + 3600000),
+                        "user": user
+                    });
+                }
+            }
+        };
+    };
+
+    // oauthType 2 so that the access token is fetched from the model
+    let buildReq = (headerDeviceId) => {
+        return {
+            "soajs": {
+                "log": {
+                    "debug": () => {
+                    }
+                },
+                "tenantOauth": {
+                    "type": 2
+                },
+                "servicesConfig": {},
+                "registry": {
+                    "serviceConfig": {
+                        "oauth": {
+                            "type": 2
+                        }
+                    }
+                }
+            },
+            "query": {},
+            "body": {},
+            "get": (what) => {
+                if ('Authorization' === what) {
+                    return "Bearer anAccessToken";
+                }
+                if ('device-id' === what) {
+                    return headerDeviceId;
+                }
+                return undefined;
+            }
+        };
+    };
+    let res = {};
+
+    it("test oauth MW - deviceId matches", (done) => {
+        let functionMw = mw(buildConfiguration("2222222222"));
+        let req = buildReq("2222222222");
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    it("test oauth MW - deviceId does not match", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = buildReq("4444444444");
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - deviceId on the token but no header", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = buildReq(undefined);
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - no deviceId on the token, check is skipped", (done) => {
+        let functionMw = mw(buildConfiguration(undefined));
+        let req = buildReq("5555555555");
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    it("test oauth MW - null deviceId on the token, check is skipped", (done) => {
+        let functionMw = mw(buildConfiguration(null));
+        let req = buildReq("5555555555");
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    // turns the check off at registry.custom.gateway.value.oauth
+    let turnCheckOff = (req, deviceIdCheck) => {
+        req.soajs.registry.custom = {
+            "gateway": {
+                "value": {
+                    "oauth": {
+                        "deviceIdCheck": deviceIdCheck
+                    }
+                }
+            }
+        };
+        return req;
+    };
+
+    it("test oauth MW - deviceId mismatch but check turned off at registry", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = turnCheckOff(buildReq("4444444444"), false);
+        functionMw(req, res, (error) => {
+            assert.ifError(error);
+            assert.ok(req.oauth.bearerToken);
+            done();
+        });
+    });
+
+    it("test oauth MW - deviceId mismatch and check explicitly turned on at registry", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = turnCheckOff(buildReq("4444444444"), true);
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - only false turns the check off, not a truthy value", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = turnCheckOff(buildReq("4444444444"), "false");
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+
+    it("test oauth MW - empty custom registry leaves the check on", (done) => {
+        let functionMw = mw(buildConfiguration("3333333333"));
+        let req = buildReq("4444444444");
+        req.soajs.registry.custom = {};
+        functionMw(req, res, (error) => {
+            assert.deepStrictEqual(error, 156);
+            done();
+        });
+    });
+});