soajs.controller 4.3.5 → 4.3.7

package/docs/configuration-custom-registry.md

@@ -18,11 +18,13 @@ registry.custom
 │       │   └── throttling          # Service-level rate limiting
 │       ├── idempotency             # Idempotency key configuration
 │       │   ├── model               # Storage backend (memory/mongo)
-│       │   └── [service]           # Per-service idempotency config
+│       │   └── services            # Per-service idempotency config
+│       │       └── [service]       # Service-specific settings
 │       ├── cache                   # GET response caching
 │       │   ├── model               # Storage backend (memory/mongo)
 │       │   ├── defaultTTL          # Default cache TTL
-│       │   └── [service]           # Per-service cache config
+│       │   └── services            # Per-service cache config
+│       │       └── [service]       # Service-specific settings
 │       ├── maintenanceMode         # Gateway maintenance mode
 │       ├── lastSeen                # User activity tracking
 │       └── gotoService
@@ -141,22 +143,24 @@ Prevents duplicate write operations by tracking requests via `Idempotency-Key` h
 {
   "idempotency": {
     "model": "memory",                    // Storage: "memory" or "mongo"
-    "av": {                               // Service name
-      "enabled": true,                    // Enable for this service
-      "ttl": 60000,                       // Key expiration (ms)
-      "apis": [                           // APIs to protect
-        "POST /av/calls",
-        "PUT /av/call/p2p/ended",
-        "PUT /av/call/p2p/rejected"
-      ]
-    },
-    "payment": {
-      "enabled": true,
-      "ttl": 120000,
-      "apis": [
-        "POST /payment/charge",
-        "POST /payment/refund"
-      ]
+    "services": {                         // Per-service configuration
+      "av": {                             // Service name
+        "enabled": true,                  // Enable for this service
+        "ttl": 60000,                     // Key expiration (ms)
+        "apis": [                         // APIs to protect
+          "POST /calls",
+          "PUT /call/p2p/ended",
+          "PUT /call/p2p/rejected"
+        ]
+      },
+      "payment": {
+        "enabled": true,
+        "ttl": 120000,
+        "apis": [
+          "POST /charge",
+          "POST /refund"
+        ]
+      }
     }
   }
 }
@@ -165,9 +169,9 @@ Prevents duplicate write operations by tracking requests via `Idempotency-Key` h
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
-| `[service].enabled` | boolean | `false` | Enable idempotency for this service |
-| `[service].ttl` | number | `60000` | Key expiration time in milliseconds |
-| `[service].apis` | string[] | `[]` | API patterns to protect (e.g., `"POST /path"`) |
+| `services.[name].enabled` | boolean | `false` | Enable idempotency for this service |
+| `services.[name].ttl` | number | `60000` | Key expiration time in milliseconds |
+| `services.[name].apis` | string[] | `[]` | API patterns to protect (e.g., `"POST /path"`) |
 
 **Client Usage:**
 ```http
@@ -194,25 +198,27 @@ Caches GET API responses with per-API TTL configuration. Returns `X-Cache: HIT`
   "cache": {
     "model": "memory",                    // Storage: "memory" or "mongo"
     "defaultTTL": 300000,                 // Default TTL: 5 minutes
-    "av": {                               // Service name
-      "enabled": true,                    // Enable caching for this service
-      "apis": {
-        "GET /av/calls": {
-          "enabled": true,
-          "ttl": 30000                    // 30 seconds
-        },
-        "GET /av/call/:id": {
-          "enabled": true,
-          "ttl": 60000                    // 60 seconds
+    "services": {                         // Per-service configuration
+      "av": {                             // Service name
+        "enabled": true,                  // Enable caching for this service
+        "apis": {
+          "GET /calls": {
+            "enabled": true,
+            "ttl": 30000                  // 30 seconds
+          },
+          "GET /call/:id": {
+            "enabled": true,
+            "ttl": 60000                  // 60 seconds
+          }
         }
-      }
-    },
-    "catalog": {
-      "enabled": true,
-      "apis": {
-        "GET /catalog/products": {
-          "enabled": true,
-          "ttl": 600000                   // 10 minutes
+      },
+      "catalog": {
+        "enabled": true,
+        "apis": {
+          "GET /products": {
+            "enabled": true,
+            "ttl": 600000                 // 10 minutes
+          }
         }
       }
     }
@@ -224,10 +230,10 @@ Caches GET API responses with per-API TTL configuration. Returns `X-Cache: HIT`
 |-------|------|---------|-------------|
 | `model` | string | `"memory"` | Storage backend: `"memory"` or `"mongo"` |
 | `defaultTTL` | number | `300000` | Default cache TTL in milliseconds |
-| `[service].enabled` | boolean | `false` | Enable caching for this service |
-| `[service].apis` | object | `{}` | API-specific cache configuration |
-| `[service].apis[api].enabled` | boolean | `false` | Enable caching for this API |
-| `[service].apis[api].ttl` | number | `defaultTTL` | Cache TTL for this specific API |
+| `services.[name].enabled` | boolean | `false` | Enable caching for this service |
+| `services.[name].apis` | object | `{}` | API-specific cache configuration |
+| `services.[name].apis[api].enabled` | boolean | `false` | Enable caching for this API |
+| `services.[name].apis[api].ttl` | number | `defaultTTL` | Cache TTL for this specific API |
 
 **Response Headers:**
 - `X-Cache: HIT` - Response served from cache
@@ -480,20 +486,24 @@ Whitelists specific APIs that can be accessed when a user is PIN-locked (during
     },
     "idempotency": {
       "model": "mongo",
-      "payment": {
-        "enabled": true,
-        "ttl": 120000,
-        "apis": ["POST /payment/charge", "POST /payment/refund"]
+      "services": {
+        "payment": {
+          "enabled": true,
+          "ttl": 120000,
+          "apis": ["POST /charge", "POST /refund"]
+        }
       }
     },
     "cache": {
       "model": "mongo",
       "defaultTTL": 300000,
-      "catalog": {
-        "enabled": true,
-        "apis": {
-          "GET /catalog/products": { "enabled": true, "ttl": 600000 },
-          "GET /catalog/categories": { "enabled": true, "ttl": 3600000 }
+      "services": {
+        "catalog": {
+          "enabled": true,
+          "apis": {
+            "GET /products": { "enabled": true, "ttl": 600000 },
+            "GET /categories": { "enabled": true, "ttl": 3600000 }
+          }
         }
       }
     },
@@ -555,7 +565,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` |
-| 7 | idempotency | `idempotency.model`, `idempotency.[service]` |
+| 7 | idempotency | `idempotency.model`, `idempotency.services.[name]` |
 | 8 | traffic | `traffic.model`, `traffic.throttling` |
-| 9 | cache | `cache.model`, `cache.defaultTTL`, `cache.[service]` |
+| 9 | cache | `cache.model`, `cache.defaultTTL`, `cache.services.[name]` |
 | 10 | lastSeen | `lastSeen` |

package/docs/middleware/cache.md

@@ -71,6 +71,10 @@ The Cache middleware provides response caching for GET APIs with per-API TTL con
           "GET /users": {
             "enabled": true
             // Uses defaultTTL (300000ms)
+          },
+          "GET /profile": {
+            "enabled": true,
+            "scope": "tenant_user"        // Cache per tenant + logged-in user
           }
         }
       },
@@ -100,6 +104,27 @@ The Cache middleware provides response caching for GET APIs with per-API TTL con
 | `services.[name].apis` | object | `{}` | API-specific cache configuration |
 | `services.[name].apis[api].enabled` | boolean | `false` | Enable caching for this API |
 | `services.[name].apis[api].ttl` | number | `defaultTTL` | Cache TTL for this API |
+| `services.[name].apis[api].scope` | string | inferred | Cache scope: `"tenant"` or `"tenant_user"`. Defaults to `"tenant"` for public APIs and `"tenant_user"` for private APIs. |
+
+## Caching Scope (Public vs Private APIs)
+
+The cache key dimension depends on whether the API is **public** (no `access_token` required) or **private** (requires an `access_token`):
+
+- **Public API** → the response is the same for the whole tenant, so it is cached per **tenant** (`scope: "tenant"`). The cache key contains the tenant id only.
+- **Private API** → the response can differ per logged-in user, so it is cached per **tenant + user** (`scope: "tenant_user"`). The cache key also includes the user id, preventing one user from receiving another user's cached response.
+
+The gateway determines public vs private automatically from `req.soajs.controller.serviceParams.isAPIPublic` and resolves the default scope accordingly. You can override the scope per API with the `scope` field.
+
+| Scope | Cache key dimension | Default for |
+|-------|---------------------|-------------|
+| `tenant` | tenant id | Public APIs |
+| `tenant_user` | tenant id + user id | Private APIs |
+
+### Safety Behavior
+
+If an API resolves to `tenant_user` scope but **no logged-in user can be resolved** (no URAC user on the request), the response is **not cached**. This prevents a user-scoped entry from being stored without a user identity and served to the wrong user. A misconfiguration therefore causes a cache miss, never a data leak.
+
+An unrecognized `scope` value is ignored (with a warning) and falls back to the inferred default.
 
 ## API Pattern Matching
 
@@ -116,16 +141,24 @@ APIs are matched using `GET /path` format with support for path parameters:
 ## Cache Key Structure
 
 ```javascript
+// Public API (scope: "tenant")
 {
   "l1": "tenant_id",
   "l2": "serviceName:GET:/path:queryHash"
 }
+
+// Private API (scope: "tenant_user")
+{
+  "l1": "tenant_id",
+  "l2": "serviceName:GET:/path:queryHash:u:user_id"
+}
 ```
 
 - **tenant_id**: Isolates cache per tenant
 - **serviceName**: The target service name
 - **path**: The API path
 - **queryHash**: MD5 hash of sorted query parameters
+- **user_id**: The logged-in user id (only for `tenant_user` scope), isolating cache per user within the tenant
 
 ### Query Parameter Handling
 
@@ -199,7 +232,9 @@ Content-Type: application/json
 ## Usage Notes
 
 - Only GET requests are cached
-- Cache is tenant-isolated
+- Cache is tenant-isolated; private APIs are additionally user-isolated (`tenant_user` scope)
+- Public APIs default to `tenant` scope, private APIs default to `tenant_user` scope
+- Private (`tenant_user`) requests without a resolved user are not cached (safety)
 - Query parameters affect cache key
 - Only 2xx responses are cached
 - Headers like `X-Cache` are not stored in cache
@@ -226,12 +261,15 @@ Content-Type: application/json
 }
 ```
 
-### User-Specific Data
+### User-Specific Data (Private API)
 
 ```javascript
-// Cache key includes tenant ID, so each tenant has separate cache
+// Private API: cache key includes tenant ID AND user ID,
+// so each user within a tenant has a separate cache entry.
+// "tenant_user" is the default scope for private APIs, shown here explicitly.
 "GET /users/profile": {
   "enabled": true,
-  "ttl": 60000    // 1 minute
+  "ttl": 60000,        // 1 minute
+  "scope": "tenant_user"
 }
 ```

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/mw/cache/index.js

@@ -106,11 +106,36 @@ module.exports = function (configuration) {
 			return next();
 		}
 
+		// Determine caching scope.
+		// Public APIs (no access_token required) return the same response for the whole
+		// tenant, so they are cached per tenant ("tenant"). Private APIs may return a
+		// different response per logged-in user, so they must be cached per tenant + user
+		// ("tenant_user") to avoid serving one user's response to another.
+		// Scope can be overridden per API in the custom registry via apiConfig.scope.
+		// Default: public -> "tenant", private -> "tenant_user".
+		const isAPIPublic = req.soajs.controller.serviceParams.isAPIPublic;
+		const userId = req.soajs.uracDriver && req.soajs.uracDriver.id;
+
+		let scope = apiConfig.scope;
+		if (scope !== 'tenant' && scope !== 'tenant_user') {
+			if (scope) {
+				configuration.log.warn('Cache: Unknown scope [' + scope + '] for API [' + method + ' ' + apiPath + ']. It can only be [tenant || tenant_user]. Falling back to default.');
+			}
+			scope = isAPIPublic ? 'tenant' : 'tenant_user';
+		}
+
+		// Safety: a user-scoped entry without a resolved user would leak across users.
+		// Skip caching rather than risk serving the wrong user's response.
+		if (scope === 'tenant_user' && !userId) {
+			return next();
+		}
+
 		const ttl = apiConfig.ttl || cacheConfig.defaultTTL || 300000;
 		const queryHash = hashQuery(req.query);
+		const userPart = (scope === 'tenant_user') ? `:u:${userId}` : '';
 		const key = {
 			'l1': req.soajs.tenant.id,
-			'l2': `${serviceName}:GET:${apiPath}:${queryHash}`
+			'l2': `${serviceName}:GET:${apiPath}:${queryHash}${userPart}`
 		};
 
 		const processCache = async () => {

package/mw/cache/model/memory.js

@@ -25,6 +25,10 @@ let model = {
 		cleanupInterval = setInterval(() => {
 			model.cleanupExpiredEntries();
 		}, CLEANUP_INTERVAL);
+		// Do not keep the event loop alive solely for the cleanup timer.
+		if (cleanupInterval.unref) {
+			cleanupInterval.unref();
+		}
 	},
 
 	'cleanupExpiredEntries': () => {

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/idempotency/model/memory.js

@@ -25,6 +25,10 @@ let model = {
 		cleanupInterval = setInterval(() => {
 			model.cleanupExpiredEntries();
 		}, CLEANUP_INTERVAL);
+		// Do not keep the event loop alive solely for the cleanup timer.
+		if (cleanupInterval.unref) {
+			cleanupInterval.unref();
+		}
 	},
 
 	'cleanupExpiredEntries': () => {

package/mw/traffic/model/memory.js

@@ -25,6 +25,10 @@ let model = {
         cleanupInterval = setInterval(() => {
             model.cleanupExpiredEntries();
         }, CLEANUP_INTERVAL);
+        // Do not keep the event loop alive solely for the cleanup timer.
+        if (cleanupInterval.unref) {
+            cleanupInterval.unref();
+        }
     },
 
     'cleanupExpiredEntries': () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soajs.controller",
   "description": "soajs multi tenant API gateway",
-  "version": "4.3.5",
+  "version": "4.3.7",
   "author": {
     "name": "soajs team",
     "email": "team@soajs.org"

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

@@ -221,7 +221,7 @@ describe("Unit test for: mw - cache", () => {
 				query: {},
 				soajs: {
 					tenant: { id: 'tenant-cache-miss' },
-					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'], isAPIPublic: true } },
 					registry: {
 						custom: {
 							gateway: {
@@ -264,7 +264,7 @@ describe("Unit test for: mw - cache", () => {
 				query: {},
 				soajs: {
 					tenant: { id: 'tenant-param-cache' },
-					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'users', '123'] } },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'users', '123'], isAPIPublic: true } },
 					registry: {
 						custom: {
 							gateway: {
@@ -306,7 +306,7 @@ describe("Unit test for: mw - cache", () => {
 				query: {},
 				soajs: {
 					tenant: { id: 'tenant-default-ttl' },
-					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'], isAPIPublic: true } },
 					registry: {
 						custom: {
 							gateway: {
@@ -345,7 +345,7 @@ describe("Unit test for: mw - cache", () => {
 				query: { page: '1', limit: '10' },
 				soajs: {
 					tenant: { id: 'tenant-query' },
-					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'], isAPIPublic: true } },
 					registry: {
 						custom: {
 							gateway: {
@@ -381,7 +381,7 @@ describe("Unit test for: mw - cache", () => {
 				query: {},
 				soajs: {
 					tenant: { id: 'tenant-empty-query' },
-					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'] } },
+					controller: { serviceParams: { name: 'test', serviceInfo: ['', 'test', 'test'], isAPIPublic: true } },
 					registry: {
 						custom: {
 							gateway: {
@@ -458,4 +458,121 @@ describe("Unit test for: mw - cache", () => {
 		});
 	});
 
+	describe("scope handling (public vs private)", () => {
+		let noopRes = {
+			setHeader: function() {},
+			writeHead: function() { return this; },
+			write: function() { return true; },
+			end: function() {}
+		};
+
+		function buildReq(serviceParamsExtra, uracDriver, apiConfig) {
+			return {
+				method: 'GET',
+				query: {},
+				soajs: {
+					tenant: { id: 'tenant-scope' },
+					uracDriver: uracDriver,
+					controller: {
+						serviceParams: Object.assign({ name: 'test', serviceInfo: ['', 'test', 'test'] }, serviceParamsExtra)
+					},
+					registry: {
+						custom: {
+							gateway: {
+								value: {
+									cache: {
+										model: 'memory',
+										services: {
+											test: { enabled: true, apis: { 'GET /test': Object.assign({ enabled: true, ttl: 30000 }, apiConfig) } }
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			};
+		}
+
+		it("public API: should cache scoped to tenant only (no user in key)", (done) => {
+			let req = buildReq({ isAPIPublic: true }, { id: 'user-1' }, {});
+			let functionMw = mw(mockConfig);
+			functionMw(req, noopRes, (error) => {
+				assert.ifError(error);
+				assert.ok(req.soajs.cacheContext, 'cacheContext should be set on MISS');
+				assert.strictEqual(req.soajs.cacheContext.key.l1, 'tenant-scope');
+				assert.strictEqual(req.soajs.cacheContext.key.l2.indexOf(':u:'), -1, 'public key must not contain user part');
+				done();
+			});
+		});
+
+		it("private API: should default to tenant_user scope (user in key)", (done) => {
+			let req = buildReq({ isAPIPublic: false }, { id: 'user-1' }, {});
+			let functionMw = mw(mockConfig);
+			functionMw(req, noopRes, (error) => {
+				assert.ifError(error);
+				assert.ok(req.soajs.cacheContext, 'cacheContext should be set on MISS');
+				assert.notStrictEqual(req.soajs.cacheContext.key.l2.indexOf(':u:user-1'), -1, 'private key must contain user part');
+				done();
+			});
+		});
+
+		it("private API: different users get different cache keys", (done) => {
+			let functionMw = mw(mockConfig);
+			let reqA = buildReq({ isAPIPublic: false }, { id: 'user-A' }, {});
+			let reqB = buildReq({ isAPIPublic: false }, { id: 'user-B' }, {});
+			functionMw(reqA, noopRes, (errA) => {
+				assert.ifError(errA);
+				functionMw(reqB, noopRes, (errB) => {
+					assert.ifError(errB);
+					assert.notStrictEqual(reqA.soajs.cacheContext.key.l2, reqB.soajs.cacheContext.key.l2, 'different users must not share a key');
+					done();
+				});
+			});
+		});
+
+		it("private API without resolved user: should skip caching (no cacheContext)", (done) => {
+			let req = buildReq({ isAPIPublic: false }, null, {});
+			let functionMw = mw(mockConfig);
+			functionMw(req, noopRes, (error) => {
+				assert.ifError(error);
+				assert.strictEqual(req.soajs.cacheContext, undefined, 'must not set cacheContext when user is unresolved');
+				done();
+			});
+		});
+
+		it("scope override: private API forced to tenant scope", (done) => {
+			let req = buildReq({ isAPIPublic: false }, { id: 'user-1' }, { scope: 'tenant' });
+			let functionMw = mw(mockConfig);
+			functionMw(req, noopRes, (error) => {
+				assert.ifError(error);
+				assert.ok(req.soajs.cacheContext, 'cacheContext should be set on MISS');
+				assert.strictEqual(req.soajs.cacheContext.key.l2.indexOf(':u:'), -1, 'overridden tenant scope must not contain user part');
+				done();
+			});
+		});
+
+		it("scope override: public API forced to tenant_user scope", (done) => {
+			let req = buildReq({ isAPIPublic: true }, { id: 'user-1' }, { scope: 'tenant_user' });
+			let functionMw = mw(mockConfig);
+			functionMw(req, noopRes, (error) => {
+				assert.ifError(error);
+				assert.ok(req.soajs.cacheContext, 'cacheContext should be set on MISS');
+				assert.notStrictEqual(req.soajs.cacheContext.key.l2.indexOf(':u:user-1'), -1, 'overridden tenant_user scope must contain user part');
+				done();
+			});
+		});
+
+		it("invalid scope: should fall back to default (private -> tenant_user)", (done) => {
+			let req = buildReq({ isAPIPublic: false }, { id: 'user-1' }, { scope: 'bogus' });
+			let functionMw = mw(mockConfig);
+			functionMw(req, noopRes, (error) => {
+				assert.ifError(error);
+				assert.ok(req.soajs.cacheContext, 'cacheContext should be set on MISS');
+				assert.notStrictEqual(req.soajs.cacheContext.key.l2.indexOf(':u:user-1'), -1, 'invalid scope must fall back to tenant_user for private API');
+				done();
+			});
+		});
+	});
+
 });

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 = {