# AuthorizationTree

This service implements class for tracking state of authorizations by means of granting or revoking access on named resources to/from users and role in a tree of nodes.

In opposition to other services, this service is primarily a class which could be instantiated to describe a tree of authorization settings. It complies with existing services by exposing a single instance as current tree of authorizations, only.

On starting application, this plugin is processing runtime configuration and local database for existing authorization rules building this tree in runtime memory for improved authorizations testing during request routing.

# Properties

# current

This static property exposes single instance of current runtime representing the tree which has been set up by the plugin on starting application. This instance is implicitly updated by some actions affecting existing users, roles and authorization rules in local database.

# Methods

Instance methods

In opposition to other services, these methods are instance methods and thus are available e.g. on current tree, only.

Instead of writing

AuthorizationTree.addRule( rule )

you must write

AuthorizationTree.current.addRule( rule )

# selectNode()

Signature: selectNode( selector, [ addIfMissing ], [ callback ] ): AuthorizationNode

This method descends into tree of nodes according to provided selector which is a resource's hierarchical name. If optional argument addIfMissing is true, any missing node is created on the fly assuring to always return a node representing selected resource.

When providing callback in third argument, it is invoked on every existing (or implicitly created) node passed while descending into tree. The callback is invoked with

  • current node,
  • segment of selector a.k.a. resource name selecting this node in context of its parent,
  • the segment's index in list of segments extracted from selector and
  • the full list of segments to be processed.

The callback may return false to prematurely stop descending into tree.

# clear()

Signature: clear(): AuthorizationTree

Clears tree by recursive deleting all its nodes. Returns tree itself for daisy-chaining calls.

# addRule()

Signature: addRule( rule ): AuthorizationTree

Adjusts tree to represent provided authorization rule. The provided rule may be instance of model AuthorizationRule or any other object resembling authorization rules by providing equivalent properties selector, user, role and accept.

Note

Adding a rule doesn't imply to eventually grant access on some resource.

The method returns current tree for daisy-chaining calls.

# removeRule()

Signature: removeRule( rule ): AuthorizationTree

This is the counterpart of addRule(). It adjusts tree to stop representing provided authorization rule.

Note

Removing a rule doesn't imply to eventually revoke access on some resource. It's reverting some previous change of tree, only.

Note

When adding a rule multiple times, it will be counted as such. You need to remove the rule as many times as it has been added before to actually remove it from tree.

The method returns current tree for daisy-chaining calls.

# isAuthorized()

Signature: isAuthorized( selector, user, role, [ acceptByDefault ] ): boolean

This method checks, whether tree is currently granting or revoking access on a selected resource to/from user and/or role.

Note

Access on a resource can be granted or revoked on particular resource. It might be granted/revoked on a superordinated resource, too.

The method takes a user or a role and checks if it is affected by any rule tracked for either node of tree which is passed on descending into tree according to provided selector. If there is no rule on any passed node affecting provided user or role, the default provided in optional fourth argument is used, which is false by default, thus preventing access by default.

The method returns true, if access is granted, and false otherwise.

# gc()

Signature: gc( [ force ] ): void

This method is meant to search tree for sparse threads and remove them if necessary. It is implicitly invoked each time a rule is removed with removeRule(), though garbage collection is triggered after seeing a certain number of calls, only. You can enforce a garbage collection by setting optional argument force.

# loadFromDatabase()

Signature: async loadFromDatabase(): void

This method is reading all existing instances of AuthorizationRule from local database invoking addRule() on every found rule.

# loadFromConfiguration()

Signature: loadFromConfiguration( configuration ): void

The method searches provided configuration for describing rules in one of several supported formats and adds them to current tree. The provided configuration can be

  • an object mapping resource names into
    • a string naming user or role granted or revoked access on named resource,
    • a string naming multiple users and/or roles separated by comma with each granted or revoked access on resource,
    • an array of either sort of string or
    • an object providing users and roles or grants and revokes in separate properties each supporting a format similar to the one of strings described above and another map of relative resource names into rules for resources subordinated to current one.