soajs.controller 4.3.14 → 4.3.15

package/docs/configuration-custom-registry.md

@@ -27,6 +27,9 @@ registry.custom
 │       │       └── [service]       # Service-specific settings
 │       ├── maintenanceMode         # Gateway maintenance mode
 │       ├── lastSeen                # User activity tracking
+│       ├── membership              # Membership on the urac object, by product
+│       │   ├── active              # Whether membership is resolved at all
+│       │   └── [main product]      # Its sub products
 │       ├── oauth
 │       │   └── deviceIdCheck       # Turn the deviceId check off
 │       └── gotoService
@@ -494,6 +497,86 @@ is read by the oauth middleware itself.
 
 ---
 
+## 14. Membership
+
+**Path:** `registry.custom.gateway.value.membership`
+
+**Middleware:** `mw/mt/index.js`, resolved by `lib/membership.js`
+
+Puts the caller's membership on the urac object of every call, so a service can read it
+without a lookup.
+
+A membership is held per main product on the user record in the urac `users` collection,
+and only its name is stored. What the name grants is resolved from the catalog, it is
+never copied onto the user:
+
+```javascript
+{
+  "memberships": [
+    { "product": "AVAPP", "membership": "whale" }
+  ]
+}
+```
+
+The gateway already resolves both halves of the match on every call. The access token
+gives the user record, which carries `memberships`, and the API key gives the product the
+call is made under. Resolution is the match between them: if the product of the request
+is a configured main product or one of its sub products, and the user holds an entry for
+that main product, the membership name is injected.
+
+```javascript
+{
+  "membership": {
+    "active": true,                          // Resolve membership at all
+    "AVAPP": ["CLUBS", "CORPS", "SECRT", "GRPCH"]   // Main product and its sub products
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `active` | boolean | `false` | Whether the gateway resolves membership at all |
+| `[main product]` | string[] | - | A product a membership is held in, valued by the sub products that resolve to it |
+
+Every key other than `active` is read as a main product, so more than one can be
+configured and they stay independent. A main product always resolves to itself, listing
+sub products is optional.
+
+### What the service sees
+
+```javascript
+req.soajs.urac.membership     // "whale"
+```
+
+Only the resolved name travels. The raw `memberships` array is never injected, so a
+service cannot read a membership held for a product the request was not made under.
+
+### It fails closed
+
+Nothing is injected, and no service sees a membership, when any of these hold:
+
+| | |
+|---|---|
+| the block is absent, or `active` is not `true` | membership is off |
+| no main product is configured | nothing is resolvable, equivalent to off |
+| the request product is neither a main product nor a sub product | out of scope |
+| the user holds no entry for the resolved main product | no membership |
+| the service does not request urac (`urac: false`) | there is no urac object to put it on |
+
+Product codes are matched exactly. They are uppercase by convention, and normalizing
+here would hide a miscased entry in the registry rather than surface it.
+
+### Freshness
+
+The user record behind this comes from the access token when
+`serviceConfig.oauth.getUserFromToken` is on, when the login mode is `oauth`, or when
+roaming. In those cases `memberships` is a snapshot taken at login, and a membership
+changed afterwards is not seen until a new token is issued. Refreshing does not help,
+the refresh grant copies the stored user forward unchanged. Otherwise the record is
+loaded from urac per request and the membership is current.
+
+---
+
 ## Complete Configuration Example
 
 ```javascript
@@ -615,6 +698,7 @@ Custom registry configurations are processed in this order:
 | 5 | gotoService/redirectToService | `gotoService.monitor` |
 | 6 | mt (security checks) | `mt.whitelist`, `oauth.value.pinWrapper`, `oauth.value.pinWhitelist` |
 | 6a | oauth (called from mt) | `oauth.deviceIdCheck` |
+| 6b | mt (inject object) | `membership` |
 | 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/mt.md

@@ -515,6 +515,7 @@ The `soajsinjectobj` header contains:
     "lastName": "Doe",
     "email": "user@example.com",
     "groups": ["group1"],
+    "membership": "whale",     // If resolved, see custom registry `membership`
     "tenant": { "id": "...", "code": "..." },
     "profile": { ... },        // If urac_Profile enabled
     "acl": { ... },            // If urac_ACL enabled

package/lib/membership.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * @license
+ * Copyright SOAJS All Rights Reserved.
+ *
+ * Use of this source code is governed by an Apache license that can be
+ * found in the LICENSE file at the root of this repository
+ */
+
+/**
+ * Resolve the membership the caller holds for the product this request is made under.
+ *
+ * A membership is held per main product on the user record, and only its name is
+ * stored. What the name grants is resolved from the catalog, it is never copied
+ * onto the user:
+ *
+ *   "memberships": [{ "product": "AVAPP", "membership": "whale" }]
+ *
+ * A request carries the product of the key it was made with. That product is either
+ * the main product itself or one of its sub products, and both resolve to the main
+ * product, so a call made under CLUBS reads the AVAPP membership.
+ *
+ * Configured at registry.custom.gateway.value.membership, keyed by main product:
+ *
+ *   {
+ *     "active": true,
+ *     "AVAPP": ["CLUBS", "CORPS", "SECRT", "GRPCH"]
+ *   }
+ *
+ * NOTE: this fails closed. An absent or inactive block, an unconfigured product, or
+ *       a user with no entry for the resolved main product all resolve to null, and
+ *       nothing is injected, so no service sees a membership it should not.
+ *
+ * @param config the custom registry membership block
+ * @param product the product the request is made under, ex: keyObj.application.product
+ * @param memberships the memberships array off the user record
+ * @returns {string|null} the membership name, or null when it does not resolve
+ */
+function resolveMembership(config, product, memberships) {
+	if (!config || !config.active) {
+		return null;
+	}
+	if (!product || !Array.isArray(memberships) || memberships.length === 0) {
+		return null;
+	}
+
+	//NOTE: product codes are matched exactly, they are uppercase by convention and
+	//      normalizing here would hide a miscased entry in the registry
+	let mainProduct = null;
+	let configuredProducts = Object.keys(config).filter((key) => {
+		return key !== "active";
+	});
+	for (let i = 0; i < configuredProducts.length; i++) {
+		let key = configuredProducts[i];
+		if (key === product || (Array.isArray(config[key]) && config[key].includes(product))) {
+			mainProduct = key;
+			break;
+		}
+	}
+	if (!mainProduct) {
+		return null;
+	}
+
+	for (let i = 0; i < memberships.length; i++) {
+		let entry = memberships[i];
+		if (entry && entry.product === mainProduct && entry.membership) {
+			return entry.membership;
+		}
+	}
+	return null;
+}
+
+module.exports = { resolveMembership };

package/mw/mt/index.js

@@ -14,6 +14,9 @@ const utils = require("./utils");
 
 
 const { encodeHeaderValue } = require("../../lib/header.js");
+const { resolveMembership } = require("../../lib/membership.js");
+
+const get = (p, o) => p.reduce((xs, x) => (xs && xs[x]) ? xs[x] : null, o);
 
 /**
  *
@@ -266,6 +269,15 @@ module.exports = (configuration) => {
 													}
 												};
 
+												//NOTE: only the resolved name travels, never the raw per product
+												//		array, so a service cannot read a membership held for
+												//		a product this request was not made under
+												let membershipConfig = get(["soajs", "registry", "custom", "gateway", "value", "membership"], req);
+												let membership = resolveMembership(membershipConfig, keyObj.application.product, uracObj.memberships);
+												if (membership) {
+													injectObj.urac.membership = membership;
+												}
+
 												injectObj.param = injectObj.param || {};
 												injectObj.param.urac_Profile = serviceParam.urac_Profile;
 												injectObj.param.urac_ACL = serviceParam.urac_ACL;

package/mw/mt/urac.js

@@ -167,6 +167,13 @@ Urac.prototype.getProfile = function (_ALL) {
 			"tenant": _self.userRecord.tenant
 		};
 
+		//NOTE: the raw per product array. The gateway resolves the one entry that applies
+		//		to this request and injects only that, see lib/membership.js. Set only when
+		//		the record carries it, so a user with no memberships keeps the shape it had.
+		if (_self.userRecord.memberships) {
+			urac.memberships = _self.userRecord.memberships;
+		}
+
 		if (_self.userRecord.socialLogin) {
 			urac.socialLogin = {
 				"strategy": _self.userRecord.socialLogin.strategy,

package/package.json

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

package/test/unit/index.js

@@ -11,6 +11,7 @@ describe("Starting Gateway Unit test", () => {
         require("./lib/http.js");
         require("./lib/ip.js");
         require("./lib/logOnce.js");
+        require("./lib/membership.js");
         require("./lib/param.js");
         require("./lib/parseURL.js");
 

package/test/unit/lib/membership.js

@@ -0,0 +1,146 @@
+"use strict";
+
+/**
+ * @license
+ * Copyright SOAJS All Rights Reserved.
+ *
+ * Use of this source code is governed by an Apache license that can be
+ * found in the LICENSE file at the root of this repository
+ */
+
+const assert = require('assert');
+const helper = require("../../helper.js");
+
+const { resolveMembership } = helper.requireModule('./lib/membership.js');
+
+describe("Unit test for: lib - membership", () => {
+
+	const CONFIG = {
+		"active": true,
+		"AVAPP": ["CLUBS", "CORPS", "SECRT", "GRPCH"]
+	};
+	const MEMBERSHIPS = [{ "product": "AVAPP", "membership": "whale" }];
+
+	describe("resolving", () => {
+
+		it("resolves when the request is made under the main product", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", MEMBERSHIPS), "whale");
+			done();
+		});
+
+		it("resolves when the request is made under a sub product", (done) => {
+			["CLUBS", "CORPS", "SECRT", "GRPCH"].forEach((sub) => {
+				assert.strictEqual(resolveMembership(CONFIG, sub, MEMBERSHIPS), "whale", "failed for " + sub);
+			});
+			done();
+		});
+
+		it("resolves the main product itself when it has no sub products", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true, "AVAPP": [] }, "AVAPP", MEMBERSHIPS), "whale");
+			done();
+		});
+
+		it("picks the entry for the resolved main product, not the first one", (done) => {
+			let memberships = [
+				{ "product": "OTHER", "membership": "minnow" },
+				{ "product": "AVAPP", "membership": "whale" }
+			];
+			assert.strictEqual(resolveMembership(CONFIG, "CLUBS", memberships), "whale");
+			done();
+		});
+
+		it("keeps several main products independent", (done) => {
+			let config = {
+				"active": true,
+				"AVAPP": ["CLUBS"],
+				"BVAPP": ["BOATS"]
+			};
+			let memberships = [
+				{ "product": "AVAPP", "membership": "whale" },
+				{ "product": "BVAPP", "membership": "dolphin" }
+			];
+			assert.strictEqual(resolveMembership(config, "CLUBS", memberships), "whale");
+			assert.strictEqual(resolveMembership(config, "BOATS", memberships), "dolphin");
+			done();
+		});
+	});
+
+	describe("failing closed", () => {
+
+		it("resolves nothing when the block is absent", (done) => {
+			assert.strictEqual(resolveMembership(null, "AVAPP", MEMBERSHIPS), null);
+			assert.strictEqual(resolveMembership(undefined, "AVAPP", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when active is not set", (done) => {
+			assert.strictEqual(resolveMembership({ "AVAPP": ["CLUBS"] }, "AVAPP", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when active is false", (done) => {
+			assert.strictEqual(resolveMembership({ "active": false, "AVAPP": ["CLUBS"] }, "CLUBS", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when no product is configured", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true }, "AVAPP", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing for a product that is neither main nor sub", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "UNRELATED", MEMBERSHIPS), null);
+			done();
+		});
+
+		it("resolves nothing when the user holds no entry for the main product", (done) => {
+			let memberships = [{ "product": "OTHER", "membership": "minnow" }];
+			assert.strictEqual(resolveMembership(CONFIG, "CLUBS", memberships), null);
+			done();
+		});
+
+		it("resolves nothing when the user has no memberships", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", null), null);
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", []), null);
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", undefined), null);
+			done();
+		});
+
+		it("resolves nothing when the request carries no product", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, null, MEMBERSHIPS), null);
+			done();
+		});
+
+		it("matches product codes exactly, a miscased code does not resolve", (done) => {
+			assert.strictEqual(resolveMembership(CONFIG, "clubs", MEMBERSHIPS), null);
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", [{ "product": "avapp", "membership": "whale" }]), null);
+			done();
+		});
+	});
+
+	describe("malformed input", () => {
+
+		it("survives a memberships array holding junk", (done) => {
+			let memberships = [null, "whale", { "product": "AVAPP" }, { "membership": "whale" }];
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", memberships), null);
+			done();
+		});
+
+		it("skips an entry with no membership name and keeps looking", (done) => {
+			let memberships = [{ "product": "AVAPP" }, { "product": "AVAPP", "membership": "whale" }];
+			assert.strictEqual(resolveMembership(CONFIG, "AVAPP", memberships), "whale");
+			done();
+		});
+
+		it("survives a sub product list that is not an array", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true, "AVAPP": "CLUBS" }, "CLUBS", MEMBERSHIPS), null);
+			assert.strictEqual(resolveMembership({ "active": true, "AVAPP": "CLUBS" }, "AVAPP", MEMBERSHIPS), "whale");
+			done();
+		});
+
+		it("does not treat active as a product", (done) => {
+			assert.strictEqual(resolveMembership({ "active": true }, "active", [{ "product": "active", "membership": "x" }]), null);
+			done();
+		});
+	});
+});