@r2d2bzh/moleculer-authz-helpers 1.0.1 → 2.0.2

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:
@@ -96,10 +133,13 @@ The signature of `isAuthorized` is `(logger) => (answer) => true | false`:
 ** `undefined`:: the responder is not able to answer
 * multiple `true` or `false` answers were provided to the same authorization request
 
-== `requestAuthorizations`
+=== `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": "1.0.1",
+  "version": "2.0.2",
   "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,12 +29,13 @@ 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 && actionSpecification.rest?.authorization !== false)
     .forEach(([actionName, actionSpecification]) => {
@@ -42,5 +44,5 @@ export default (serviceSchema) => {
       }
     });
 
-  return unsafeAddPreflightMixin(serviceSchema);
+  return unsafeAddPreflightMixin(serviceSchema, { timeout });
 };

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 })
+    )
+  );