@qikdev/sdk/src/api/qik.access.js

Promise based Javascript SDK

/**
 * Creates a new Access Module instance.
 * This module provides a number of helper functions for managing and understanding permissions of the current
 * application or user
 * @alias access
 * @constructor
 * @hideconstructor
 * @param {QikCore} qik A reference to the parent instance of the QikCore module. This module is usually created by a QikCore instance that passes itself in as the first argument.
 */

var QikAccess = function (QikCore) {
  if (!QikCore.auth) {
    throw new Error(
      `Can't Instantiate QikAccess before QikAccess has been initialized`,
    );
  }

  if (!QikCore.utils) {
    throw new Error(
      `Can't Instantiate QikAccess before QikCore.utils has been initialized`,
    );
  }

  //////////////////////////////////

  var service = {};

  ///////////////////////////////////////////////

  /**
   * @alias access.hasFeature
   * @description Checks if a user has a specific feature enabled for their organisation
   * @param  {Object} user The user to check
   * @param  {String} feature The feature to check is enabled/disabled
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const formsFeatureIsEnabled =  sdk.access.hasFeature(user, 'forms');
   */
  service.hasFeature = function (user, feature) {
    const features = user?.organisation?.features || {};
    if (features.all) {
      return true;
    }
    return Boolean(features[feature]);
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.isAdministrator
   * @description Check if a user object is an administrator
   * @param  {Object} user The user session to check
   * @example
   * const userIsAnAdministrator = sdk.access.isAdministrator({firstName:'Jeffrey', lastName:'Winger', ...});
   */
  service.isAdministrator = function (user) {
    return user && user?.userType == "administrator";
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.getAllDescendants
   * @description Get all children of a specified scope
   * @param  {Object} scope A scope object with child scopes
   * @example
   * const childScopes = sdk.access.getAllDescendants({title:'Global', children:[{title:'Australia', ...}, {title:'New Zealand', ...}]});
   */
  service.getAllDescendants = function (scope) {
    //Start by including the scope id
    var results = [];

    addScope(scope);

    function addScope(entry) {
      //Add this scope to the results
      var id = QikCore.utils.id(entry);
      results.push(id);

      (entry.children || []).forEach(function (child) {
        addScope(child);
      });
    }
    return results;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.hashPermissions
   * @description Get a lookup of all permissions a user has been granted
   * @param  {Object} user A user session object
   * @example
   * const permissions = sdk.access.hashPermissions({firstName:'Mighty', lastName:'Mouse', permissionSets:[...], ...});
   */
  service.hashPermissions = function (user) {
    var results = {};

    for (var key in user?.permissions || {}) {
      //Get the permission set
      var permissionSet = user?.permissions[key];

      //Get all Scope ids from the permission set
      var allIDs = service.getAllDescendants(permissionSet);

      //For each permission defined in the set
      (permissionSet.permissions || []).forEach(function (permissionString) {
        //Include the top scope
        if (!results[permissionString]) {
          results[permissionString] = [];
        }
        results[permissionString] = [
          ...new Set(results[permissionString].concat(allIDs)),
        ];
      });
    }

    ///////////////////////////////////////////////

    return results;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.allUserScopes
   * @description Return an array of ids of all scopes that a given user has been granted a permission in
   * @param  {Object} user A user session object
   * @example
   * const permissions = sdk.access.allUserScopes({firstName:'Mighty', lastName:'Mouse', permissionSets:[...], ...});
   *
   * // Would result in:
   * ['61eca4746971e75c1fc670cf', '61eca4746971e75c1fc670ca', '77eca4746971e75c1fc670cf'],
   */
  service.allUserScopes = function (user) {
    var collected = {};
    var permissions = user?.permissions || {};

    ////////////////////////

    function pluckScope(scopeObject) {
      if (!scopeObject) {
        return;
      }

      var scopeID = QikCore.utils.id(scopeObject);
      if (!scopeID) {
        return;
      }

      //Add to the collection
      collected[scopeID] = 1;

      //If there are children, then recursively pluck the ids
      if (scopeObject.children && scopeObject.children.length) {
        scopeObject.children.forEach(function (scope) {
          pluckScope(scope);
        });
      }
    }

    ////////////////////////

    for (var scopeID in permissions) {
      pluckScope(permissions[scopeID]);
    }

    ////////////////////////

    return Object.keys(collected);
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.actionableScopes
   * @description Return an array of all scopes that a given user can perform a specified action in
   * @param  {Object} user A user session object
   * @param  {String} action The action
   * @param  {String} definition The defined type of item the action will be performed on
   * @param  {String} type The basic type of item the action will be performed on
   * @param  {Object} options Additional options and parameters
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const canCreateInScopes = sdk.access.actionableScopes(user, 'create', 'car', 'article');
   * const canDeleteInScopes = sdk.access.actionableScopes(user, 'delete', 'profile');
   *
   * // Would result in something like:
   * ['61eca4746971e75c1fc670cf', '61eca4746971e75c1fc670ca', '77eca4746971e75c1fc670cf'],
   */
  service.actionableScopes = function (
    user,
    action,
    definition,
    type,
    options,
  ) {
    options = options || {};

    /////////////////////////

    var validScopes = [];

    if (user?.userType == "administrator") {
      validScopes = service.allUserScopes(user, options);
    } else {
      var permissionsLookup = service.hashPermissions(user);

      var checkTypeName = definition || type;
      if (!checkTypeName) {
        return validScopes;
      }

      let definitionScopes = !definition
        ? []
        : permissionsLookup[`${definition}.${action}`] || [];
      let typeScopes = !type
        ? []
        : permissionsLookup[`${type}.${action}`] || [];

      validScopes = [...definitionScopes, ...typeScopes];
    }

    /////////////////////////

    return validScopes || [];
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.isOwner
   * @description Return whether or not a user is considered an Owner of a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const item = {title:'A piece of content', meta:{personaAuthor:'61eca4746971e75c1fc670ca'}, ...}
   *
   * // Returns true if the user owns the item
   * const isTheOwner = sdk.access.isOwner(user, item);
   */
  service.isOwner = function (user, item) {
    var userID = QikCore.utils.id(user);
    var personaID = QikCore.utils.id(user?.persona);

    var metaObject = item.meta;
    if (!metaObject) {
      return false;
    }

    /////////////////////////////////////////////

    var userOwners = metaObject.userOwners || [];

    var users = QikCore.utils.ids([...userOwners, metaObject.userAuthor]);
    var userHash = QikCore.utils.hash(users);

    if (userHash[userID]) {
      return true;
    }

    /////////////////////////////////////////////

    var personaOwners = metaObject.personaOwners || [];

    var personas = QikCore.utils.ids([
      ...personaOwners,
      metaObject.personaAuthor,
    ]);
    var personaHash = QikCore.utils.hash(personas);

    if (personaHash[personaID]) {
      return true;
    }

    const isAssignee = service.isAssignee(user, item);

    return isAssignee;
  };

  /**
   * @alias access.isAssignee
   * @description Return whether or not a user is an assignee of a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const item = {title:'A workflow card', assignees:['61eca4746971e75c1fc670ca'], ...}
   *
   * // Returns true if the user owns the item
   * const isAssignee = sdk.access.isAssignee(user, item);
   */
  service.isAssignee = function (user, contentItem) {
    // Check the user profile ids
    const profileIDs = QikCore.utils.ids(user?.profiles);
    if (!profileIDs.length) {
      return false;
    }

    // Check if the content item has assignees set
    const assigneeIDs = QikCore.utils.ids(contentItem.assignees);

    if (!assigneeIDs.length) {
      return false;
    }

    // Return the intersection of assignees and profile ids
    const set = new Set(assigneeIDs);
    const matches = profileIDs.filter((item) => set.has(item));
    const isAssignee = !!matches.length;

    return isAssignee;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.allPermissions
   * @description Returns an array of all permissions a given user has access to
   * @param  {Object} user The user to check
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const permissions =  sdk.access.allPermissions(user);
   *
   * // Returns
   * ['image.viewany', 'testimonial.viewany', 'testimonial.viewfield.title', ...]
   */
  service.allPermissions = function (user) {
    var allPermissions = Object.values(user?.permissions || {})
      .map(function (permissionScope) {
        return permissionScope.permissions;
      })
      .flat();

    return allPermissions;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.allPermissionTypes
   * @description Returns an array of content types a given user has permission to interact with
   * @param  {Object} user The user to check
   * @param  {Boolean} asHash Whether to retrieve the result as a keyed object hash, by default
   * the response will be an array
   * @example
   * const user = sdk.auth.getCurrentUser();
   *
   * // Returns ['image', 'testimonial']
   * const types = sdk.access.allPermissionTypes(user);
   *
   * // Returns {image:true, testimonial:true}
   * const types = sdk.access.allPermissionTypes(user, true);
   */
  service.allPermissionTypes = function (user, asHash) {
    if (asHash) {
      return service.allPermissions(user).reduce(function (set, string) {
        var type = string.split(".")[0];
        set[type] = true;
        return set;
      }, {});
    } else {
      return service.allPermissions(user).map(function (string) {
        return string.split(".")[0];
      });
    }
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canKnowOf
   * @description Checks if a user has any permissions relating to a specified type of content
   * @param  {Object} user The user to check
   * @param  {String} typeKey The type or definition to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const canAccessImageSection =  sdk.access.canKnowOf(user, 'image');
   * const canAccessCustomerUploadSection =  sdk.access.canKnowOf(user, 'customerUpload');
   */
  service.canKnowOf = function (user, typeKey, options) {
    options = options || {};
    options.cache = options.cache || {};

    //Let us know if there are any permissions for this user
    return service.allPermissionTypes(user, true)[typeKey];
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.checkActionAccess
   * @description Helpful function for checking whether a given user has access to do a given action on a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item to check
   * @param  {String} ANY_ACTION The 'any' action to check
   * @param  {String} OWN_ACTION The 'owned' action to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const canEditItem =  sdk.access.checkActionAccess(user, {_id:'61eca4746971e75c1fc670ca', meta:{...}}, 'editany', 'editown');
   * const canViewItem =  sdk.access.checkActionAccess(user, {_id:'61eca4746971e75c1fc670ca', meta:{...}}, 'viewany', 'viewown');
   *
   * // Example of looping through a large array of items
   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
   *
   * // Create an in memory cache object outside of the loop
   * const cache = {}
   *
   * const filtered = largeArrayOfItems.filter(function(item) {
   *    return sdk.access.checkActionAccess(user, item, 'editany', 'editown', {cache});
   * })
   */
  service.checkActionAccess = function (
    user,
    item,
    ANY_ACTION,
    OWN_ACTION,
    options,
  ) {
    options = options || {};
    options.cache = options.cache || {};

    //Allow everything if we're a super user
    if (service.isAdministrator(user)) {
      return true;
    }

    //////////////////////////////////

    var type = item.meta?.type;
    var definition = item.meta?.definition || type;

    if (!definition) {
      return false;
    }

    //////////////////////////////////

    //The user should be able to list any scopes that they have
    //permission to do things in.
    if (ANY_ACTION == "listany" || OWN_ACTION == "listown") {
      if (type === "scope") {
        var itemID = QikCore.utils.id(item);
        return !!user.permissions[itemID];
      }
    }

    //////////////////////////////////

    var itemScopes = QikCore.utils.ids(item.meta.scopes || []);

    //Scopes don't have meta.scopes, instead use the scope's
    //path (ancestors) plus the scope's own ID
    if (type === "scope") {
      itemScopes = [
        ...QikCore.utils.ids(item.path || []),
        QikCore.utils.id(item),
      ];
    }

    //////////////////////////////////

    var actionAnyScopesHash;
    var anyCacheKey = `access-${user?.cacheKey}-${ANY_ACTION}-${definition}-${type}`;

    if (options.cache[anyCacheKey]) {
      actionAnyScopesHash = options.cache[anyCacheKey];
    } else {
      //Check if we can action this type of thing in any scopes
      var actionAnyScopes = QikCore.utils.ids(
        service.actionableScopes(user, ANY_ACTION, definition, type, options),
      );

      //Get a fash hash of the scopes
      actionAnyScopesHash = QikCore.utils.hash(actionAnyScopes);
      options.cache[anyCacheKey] = actionAnyScopesHash;
    }

    //////////////////////////////////

    //If we have data about what they can do
    if (actionAnyScopesHash) {
      //Check if the item is in any of the scopes the user can access
      var isInAnyScopes = itemScopes.some(function (scopeID) {
        return actionAnyScopesHash[scopeID];
      });

      if (isInAnyScopes) {
        return true;
      }
    }

    //////////////////////////////////

    //Check if the user owns this content
    var isOwner = service.isOwner(user, item);

    //If the user is the owner
    if (isOwner) {
      var actionOwnScopesHash;
      var ownCacheKey = `access-${user?.cacheKey}-${OWN_ACTION}-${definition}-${type}`;

      if (options.cache[ownCacheKey]) {
        actionOwnScopesHash = options.cache[ownCacheKey];
      } else {
        //Check if we can action this type of thing in any scopes
        var actionOwnScopes = QikCore.utils.ids(
          service.actionableScopes(user, OWN_ACTION, definition, type, options),
        );

        //Get a fash hash of the scopes
        actionOwnScopesHash = QikCore.utils.hash(actionOwnScopes);
        options.cache[ownCacheKey] = actionOwnScopesHash;
      }

      //If we have data about what they can do
      if (actionOwnScopesHash) {
        //Check if the item is in any of the scopes the user can access
        var isInOwnScopes = itemScopes.some(function (scopeID) {
          return actionOwnScopesHash[scopeID];
        });

        if (isInOwnScopes) {
          return true;
        }
      }
    }

    //////////////////////////////////

    //No access by default
    return false;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.has
   * @description Helpful function for checking whether a given user has a specified permission
   * @param  {Object} user The user to check
   * @param  {String} permission The permission the user may have been granted
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const isAllowedToCreateItems = sdk.access.has(user, 'video.create');
   */
  service.has = function (user, permission) {
    //Allow everything if we're a super user
    if (service.isAdministrator(user)) {
      return true;
    }

    var permissionsLookup = service.hashPermissions(user);
    return permissionsLookup[permission];
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canCreate
   * @description Helpful function for checking whether a given user can create a specified type of item
   * @param  {Object} user The user to check
   * @param  {String} definition The defined type key
   * @param  {String} type The basic type key
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   * const userCanCreateShortFilms = sdk.access.canCreate(user, 'shortFilm', 'video');
   */
  service.canCreate = function (user, definition, type, options) {
    options = options || {};
    options.cache = options.cache || {};

    //Allow everything if we're a super user
    if (service.isAdministrator(user)) {
      return true;
    }

    var createableScopes = service.actionableScopes(
      user,
      "create",
      definition,
      type,
    );
    return createableScopes.length;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canListItem
   * @description Helpful function for checking whether a given user can list a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   *
   * // Example of looping through a large array of items
   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
   *
   * // Create an in memory cache object outside of the loop
   * const cache = {}
   *
   * const filtered = largeArrayOfItems.filter(function(item) {
   *    return sdk.access.canListItem(user, item, {cache});
   * })
   */
  service.canListItem = function (user, item, options) {
    options = options || {};
    options.cache = options.cache || {};

    //Check if we can list the item
    var canList = service.checkActionAccess(
      user,
      item,
      "listany",
      "listown",
      options,
    );

    if (canList) {
      return true;
    }

    //If we can view the item then we should be able to list it also
    var canView = service.canViewItem(user, item, options);
    if (canView) {
      return true;
    }

    return false;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canViewItem
   * @description Helpful function for checking whether a given user can view a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   *
   * // Example of looping through a large array of items
   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
   *
   * // Create an in memory cache object outside of the loop
   * const cache = {}
   *
   * const filtered = largeArrayOfItems.filter(function(item) {
   *    return sdk.access.canViewItem(user, item, {cache});
   * })
   */
  service.canViewItem = function (user, item, options) {
    options = options || {};
    options.cache = options.cache || {};

    //Check if we can view the item
    var canView = service.checkActionAccess(
      user,
      item,
      "viewany",
      "viewOwn",
      options,
    );
    if (canView) {
      return true;
    }

    //If we can edit the item then we should be able to view it also
    var canEdit = service.canEditItem(user, item, options);
    if (canEdit) {
      return true;
    }

    return false;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canEditItem
   * @description Helpful function for checking whether a given user can edit a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   *
   * // Example of looping through a large array of items
   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
   *
   * // Create an in memory cache object outside of the loop
   * const cache = {}
   *
   * const filtered = largeArrayOfItems.filter(function(item) {
   *    return sdk.access.canEditItem(user, item, {cache});
   * })
   */
  service.canEditItem = function (user, item, options) {
    options = options || {};
    options.cache = options.cache || {};

    var allowed = service.checkActionAccess(
      user,
      item,
      "editany",
      "editown",
      options,
    );

    return allowed;
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canDeleteItem
   * @description Helpful function for checking whether a given user can delete a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   *
   * // Example of looping through a large array of items
   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
   *
   * // Create an in memory cache object outside of the loop
   * const cache = {}
   *
   * const filtered = largeArrayOfItems.filter(function(item) {
   *    return sdk.access.canDeleteItem(user, item, {cache});
   * })
   */
  service.canDeleteItem = function (user, item, options) {
    options = options || {};
    options.cache = options.cache || {};

    return service.checkActionAccess(
      user,
      item,
      "deleteany",
      "deleteown",
      options,
    );
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canRestoreItem
   * @description Helpful function for checking whether a given user can restore a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   *
   * // Example of looping through a large array of items
   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
   *
   * // Create an in memory cache object outside of the loop
   * const cache = {}
   *
   * const filtered = largeArrayOfItems.filter(function(item) {
   *    return sdk.access.canRestoreItem(user, item, {cache});
   * })
   */
  service.canRestoreItem = function (user, item, options) {
    options = options || {};
    options.cache = options.cache || {};

    return service.checkActionAccess(
      user,
      item,
      "restoreany",
      "restoreown",
      options,
    );
  };

  ///////////////////////////////////////////////

  /**
   * @alias access.canEraseItem
   * @description Helpful function for checking whether a given user can erase a specified item
   * @param  {Object} user The user to check
   * @param  {Object} item The item to check
   * @param  {Object} options Additional options and parameters
   * @param  {Object} options.cache Provide an existing object to use as an in memory cache, can be useful to increase performance if running this function in a large for/while loop
   * @example
   * const user = sdk.auth.getCurrentUser();
   *
   * // Example of looping through a large array of items
   * const largeArrayOfItems = [{_id:'...', title...}, {_id:'...', title...}...]
   *
   * // Create an in memory cache object outside of the loop
   * const cache = {}
   *
   * const filtered = largeArrayOfItems.filter(function(item) {
   *    return sdk.access.canEraseItem(user, item, {cache});
   * })
   */
  service.canEraseItem = function (user, item, options) {
    options = options || {};
    options.cache = options.cache || {};

    return service.checkActionAccess(
      user,
      item,
      "eraseany",
      "eraseown",
      options,
    );
  };

  return service;
};

///////////////////////////////////////////////////////////////////////////////

export default QikAccess;