Director

Directors provide conversation firewalls, allowing listed users to be authorised or blocked from entering scenes or preventing listeners from firing.

Access is determined by blacklist or whitelist, or if defined, a custom fallback function can determine to allow or deny anyone not on the list.

A director can be attached to whole scenes or dialogues, or even specific listeners.

Authorise function is given the user or room name (depending on the scope configured for the direcrot) and response object. It must return a boolean to determine access.

config.deniedReply can be set globally with environment var DENIED_REPLY

Environment vars can also provide global default lists:

• WHITELIST_USERNAMES for whitelist type and username scope directors
• WHITELIST_ROOMS for whitelist type and room scope directors
• BLACKLIST_USERNAMES for blacklist type and username scope directors
• BLACKLIST_ROOMS for blacklist type and room scope directors

Kind: global class

• Director
  • new Director(robot, [authorise], [options], [key])
  • .add(names) ⇒ Director
  • .remove(names) ⇒ Director
  • .isAllowed(res) ⇒ Boolean/Promise
  • .process(res) ⇒ Promise
  • .directMatch(regex) ⇒ Director
  • .directListener(id) ⇒ Director
  • .directScene(scene) ⇒ Director

---

new Director(robot, [authorise], [options], [key])

Param	Type	Description
robot	Robot	Hubot Robot instance
[authorise]	function	Function to determine access (as fallback)
[options]	Object	Key/val options for config
[options.type]	string	‘whitelist’ (default) or ‘blacklist’
[options.scope]	string	‘username’ (default) or ‘room’
[options.deniedReply]	string	Sent when denied access
[key]	string	Key name for this instance

Example (check if user has a particular role in platform)

let adminsOnly = new Director(robot, (username) => {
  return chatPlatform.userHasPermission(username, 'admin')
})
// ...when directing a scene, will only allow platform admins to enter.

---

director.add(names) ⇒ Director

Add new usernames/rooms to list.

Kind: instance method of Director
Returns: Director - Self, for chaining methods

Param	Type	Description
names	string/array	Usernames or Room names (depending on scope)

---

director.remove(names) ⇒ Director

Remove new usernames/rooms from list.

Kind: instance method of Director
Returns: Director - Self, for chaining methods

Param	Type	Description
names	string/array	Usernames or Room names (depending on scope)

---

director.isAllowed(res) ⇒ Boolean/Promise

Determine if user has access, checking usernames/rooms against lists.

Blacklist blocks names on list, let anyone else through. Whitelist lets names on list through, block anyone else. Whitelist is default behaviour.

Kind: instance method of Director
Returns: Boolean/Promise - Access allowed - should wrap in resolve

Param	Type	Description
res	Response	Hubot Response object

Example (assumes res1, res2 are valid Response objects)

let noHomers = new Director(robot, { type: 'blacklist' }).add('homer')
res1.message.user.name = 'homer'
res2.message.user.name = 'marge'
noHomers.isAllowed(res1) // false
noHomers.isAllowed(res2) // true

---

director.process(res) ⇒ Promise

Process access or denial (either silently or with reply, as configured).

Kind: instance method of Director
Returns: Promise - Resolves with boolean, access allowed/denied

Param	Type	Description
res	Response	Hubot Response object

---

director.directMatch(regex) ⇒ Director

Let this director control access to any listener matching regex.

Kind: instance method of Director
Returns: Director - Self, for chaining methods

Param	Type	Description
regex	Regex	Listener match pattern

---

director.directListener(id) ⇒ Director

Let this director control access to a listener by listener ID.

If multiple listeners use the same ID, it’s assumed to deny all of them.

Kind: instance method of Director
Returns: Director - Self, for chaining methods

Param	Type	Description
id	string	Listener ID (may be multiple for scene)

---

director.directScene(scene) ⇒ Director

Let this director control access to a given scene’s listener.

Also hooks into Scene.enter to control access to manually entered scenes.

Kind: instance method of Director
Returns: Director - Self, for chaining methods

Param	Type	Description
scene	Scene	The Scene instance

---