@r2d2bzh/moleculer-authz-helpers 0.0.3 → 2.0.1

package/README.adoc

@@ -2,8 +2,18 @@
 :sectnums:
 :toc: left
 
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
 = Moleculer authorization helpers
 
+== Rationale
+
 The current authorization strategy used by the R2D2 stack is to operate a preflight from the API gateway before it actually calls an action of a backend service.
 These preflight actions can either decide themselves if the call is authorized or ask other services for an authorization.
 
@@ -11,17 +21,44 @@ These requests are sent through Moleculer events.
 Services subscribing to these events will either reply with a boolean (`true` = authorized, `false` = forbidden) or will not reply if they cannot answer (`undefined` answer).
 An authorization request is considered successful if at least one service has authorized the request and no service has forbidden the request (which means that if nobody answered, the request is implicitly forbidden).
 
+[NOTE]
+====
+Events are used instead of actions as the authorization requester does not necessarily know which service answers its authorization requests.
+Moreover, multiple services could be responsible to answer one authorization request.
+====
+
+=== Use case
+
+The following example considers a shared todo list service.
+This service exposes an action to update a todo item and notify by email the todo list members of this update. +
+Depending on the user, the email sender will authorize or not the notification.
+
+The following services are at play:
+
+* todo-list: manage todo lists 
+* email-sender: send emails
+* members-service: manage users
+* moleculer-web: expose actions
+
+image::docs/use-case.svg[]
+
+== Helpers
+
 Currently, this library provides the following helpers:
 
 * `addPreflightMixin` to build and add a preflight mixin in a service schema
 * `isAuthorized` to decide whether one or more authorization requests have all succeeded based on the answers provided by the subscribers
 * `requestAuthorizations` to send multiple authorization requests at once
 
-== `addPreflightMixin`
+=== `addPreflightMixin`
 
 This helper adds a service mixin used to generate preflight actions for actions exposed through rest.
 It takes a Moleculer service schema as a parameter and returns the same service schema with the mixin added.
 
+This helper also adds the `callEventMixin` provided by https://www.npmjs.com/package/@r2d2bzh/moleculer-event-callback[@r2d2bzh/moleculer-event-callback].
+`callEventMixin` injects a `$$callEvent` method to make authorization requests.
+It also provides the callback action needed to receive the return value of authorization requests.
+
 NOTE: A preflight action takes the same parameters as the original action.
 
 To define a preflight handler, you must add a preflight attribute to an action:
@@ -67,7 +104,7 @@ Only actions where authorization is disabled do not enforce a preflight:
 ----
 ==== 
 
-== `isAuthorized`
+=== `isAuthorized`
 
 This helper decides whether or not something is authorized based on the answers to one or more authorization requests.
 It implements the following rules:
@@ -83,10 +120,26 @@ It implements the following rules:
 * if any answer is `false`, the whole authorization process fails
 * if no answer was provided, the whole authorization process fails
 
-== `requestAuthorizations`
+The signature of `isAuthorized` is `(logger) => (answer) => true | false`:
+
+. the `logger` curried argument must provide a `warn` method used to issue warnings (default: `console`)
+. the `answer` curried argument is the authorization answer(s) to one or many authorization requests
+
+`isAuthorized` will raise a warning in the following cases:
+
+* an odd authorization answer was provided, known answers are:
+** `true`:: the request is authorized
+** `false`:: the request is denied
+** `undefined`:: the responder is not able to answer
+* multiple `true` or `false` answers were provided to the same authorization request
+
+=== `requestAuthorizations`
 
 This helper operates multiple authorization requests at once and returns a promise which result can be handled by `isAuthorized`.
 
+This helper uses the `$$callEvent` method provided by the `callEventMixin` of https://www.npmjs.com/package/@r2d2bzh/moleculer-event-callback[@r2d2bzh/moleculer-event-callback] (see `addPreflightMixin`).
+This allows the retrieval of authorization requests return values.
+
 [source,javascript]
 ----
 requestAuthorization(moleculerContext)([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r2d2bzh/moleculer-authz-helpers",
-  "version": "0.0.3",
+  "version": "2.0.1",
   "description": "Moleculer mixin to implement preflight runner",
   "main": "index.js",
   "type": "module",
@@ -39,7 +39,10 @@
     "node": ">=12.0.0"
   },
   "peerDependencies": {
-    "lodash": "^4.17.21",
     "moleculer": "^0.14.0"
+  },
+  "dependencies": {
+    "@r2d2bzh/moleculer-event-callback": "~0.0.1",
+    "lodash": "^4.17.21"
   }
 }

package/src/add-preflight-mixin.js

@@ -1,11 +1,12 @@
 import cloneDeep from 'lodash/cloneDeep.js';
 import moleculer from 'moleculer';
+import { callEventMixin } from '@r2d2bzh/moleculer-event-callback';
 
 const {
   Errors: { MoleculerError },
 } = moleculer;
 
-export const unsafeAddPreflightMixin = (serviceSchema) => {
+export const unsafeAddPreflightMixin = (serviceSchema, { timeout }) => {
   const actionsWithPreflight = Object.entries(serviceSchema.actions || {}).filter(
     ([, actionSpecification]) => actionSpecification?.preflight
   );
@@ -28,19 +29,20 @@ export const unsafeAddPreflightMixin = (serviceSchema) => {
     {
       actions: Object.fromEntries(preflightActions),
     },
+    callEventMixin({ timeout }),
   ];
 
   return schema;
 };
 
-export default (serviceSchema) => {
+export default (serviceSchema, { timeout = 200 } = {}) => {
   Object.entries(serviceSchema.actions || {})
-    .filter(([, actionSpecification]) => actionSpecification?.rest?.authorization !== false)
+    .filter(([, actionSpecification]) => actionSpecification?.rest && actionSpecification.rest?.authorization !== false)
     .forEach(([actionName, actionSpecification]) => {
       if (!(actionSpecification?.preflight instanceof Function || actionSpecification?.preflight?.handler)) {
         throw new MoleculerError('missing preflight handler', 500, 'MISSING_PREFLIGHT', { actionName });
       }
     });
 
-  return unsafeAddPreflightMixin(serviceSchema);
+  return unsafeAddPreflightMixin(serviceSchema, { timeout });
 };

package/src/is-authorized.js

@@ -1,19 +1,62 @@
 const removeUnanswered = (authzAnswers) => authzAnswers.filter((answer) => answer !== undefined);
 
-const doAnswersAuthorize = (authzAnswers) =>
-  authzAnswers.length
-    ? authzAnswers.reduce((isAuthorized, authzAnswer) => isAuthorized && doesAnswerAuthorize(authzAnswer), true)
-    : false;
+const reduceAnswers = (answers, reducer) =>
+  answers.length
+    ? answers.reduce(
+        ([authorizationStatus, authorizationsCount], answer) =>
+          reducer(answer, authorizationStatus, authorizationsCount),
+        [true, 0]
+      )
+    : [false, 0];
 
-const doesAnswerAuthorize = function (something) {
-  switch (Object.prototype.toString.call(something)) {
-    case '[object Boolean]':
-      return something;
-    case '[object Array]':
-      return doAnswersAuthorize(removeUnanswered(something));
-    default:
-      return false;
-  }
+const onMultipleAuthorizations =
+  (handle) =>
+  ([answersAuthorization, authorizationsCount]) => {
+    if (authorizationsCount > 1) {
+      handle(authorizationsCount);
+    }
+    return answersAuthorization;
+  };
+
+const processAndCountManyAnswers = (warn) => {
+  const warnOnMultipleAuthorizations = onMultipleAuthorizations((authorizationsCount) =>
+    warn(`multiple answers to the same authorization request (${authorizationsCount})`)
+  );
+  return (answers, authorizationStatus) => {
+    const newRequestIsAuthorized = warnOnMultipleAuthorizations(
+      reduceAnswers(removeUnanswered(answers), processAndCountAnswer(warn))
+    );
+    return authorizationStatus && newRequestIsAuthorized;
+  };
+};
+
+const processAndCountAnswer = (warn) => {
+  const doAnswersAuthorize = processAndCountManyAnswers(warn);
+  return function (answer, authorizationStatus = true, authorizationsCount = 0) {
+    switch (Object.prototype.toString.call(answer)) {
+      case '[object Boolean]':
+        return [authorizationStatus && answer, authorizationsCount + 1];
+      case '[object Array]':
+        // A new array means a new authorization request with its own
+        // answers count that does not reflect on the current one
+        return [doAnswersAuthorize(answer, authorizationStatus), authorizationsCount];
+      case '[object Undefined]':
+        return [false, authorizationsCount];
+      default:
+        warn(`odd authorization answer (${answer})`);
+        return [false, authorizationsCount];
+    }
+  };
 };
 
-export default doesAnswerAuthorize;
+export default (logger) => {
+  try {
+    const doesAnswerAuthorizeAndWarn = processAndCountAnswer(logger.warn.bind(logger));
+    return function (answer) {
+      const [authorize] = doesAnswerAuthorizeAndWarn(answer);
+      return authorize;
+    };
+  } catch (e) {
+    throw new Error(`logger.warn must be a function`);
+  }
+};

package/src/request-authorizations.js

@@ -1,2 +1,6 @@
 export default (ctx) => (requests) =>
-  Promise.all(requests.map(({ eventName, parameters, options }) => ctx.emit(eventName, parameters, options)));
+  Promise.all(
+    requests.map(({ eventName, parameters, options }) =>
+      ctx.service.$$callEvent(ctx, { eventName, payload: parameters, options })
+    )
+  );