@allstar/hemera-permission

    2.0.0 • Public • Published

    Hemera ACL

    Hemera pluging adding Access control via coarse based roles, or granular permissions

    Installation

    $ npm install @allstar/hemera-acl

    Usage

    Basic Setup

    const Hemera = require('nats-hemera')
    const nats = require('nats')
    const Acl = require('@allstar/hemera-acl')
     
    const nc = nats.connect({
      servers: ['nats://0.0.0.0:4222']
    })
     
    const hmera = new Hemera(nc)
    hemera.use(acl, {
      separator: ':' // default
    })
     
    hemera.ready(() => {
      // go!
    })

    Roles

    For coarse control, handlers can define a roles array (or single string) specifying the roles that are allowed

    hemera.add({
      topic: 'math'
    , cmd: 'add'
    , auth$: {
        roles: 'admin' // only admin access
      }
    }, function(req, cb) {
      // admin user
      console.log(this.user$)
      cb(null, true)
    })
     
    hemera.add({
      topic: 'math'
    , cmd: 'subtract'
    , auth$: {
        roles: ['admin', 'manager'] // admin OR manager access
      }
    }, function(req, cb) {
      // admin user
      console.log(this.user$)
      cb(null, true)
    })
     
    hemera.add({
      topic: 'math'
    , cmd: 'divide'
    , auth$: {
        roles: [] // no roles - superuser access only
      }
    }, function(req, cb) {
      // admin user
      console.log(this.user$)
      cb(null, true)
    })
    Calling w/ roles

    Adding a userobject to the hemera metadata with the roles array key populated to pass acl validation. Request that do not pass authorization will return an error with the code EAUTH. Users with the special key superuser set tot true will always pass authorization

    hemera.act({
      topic: 'math'
    , cmd: 'add'
    , meta$: {
        user: {
          roles: ['salesman', 'admin'] // passes authorization for the add handler
        }
      }
    }, function(err, res) {
      console.log(res)
    })
     
    hemera.act({
      topic: 'math'
    , cmd: 'subtract'
    , meta$: {
        user: {
          roles: ['grunt'] // fails validatin for the subtract handler
        }
      }
    }, function(err, res) {
      console.log(err.code) // EAUTH
    })
     
    hemera.act({
      topic: 'math'
    , cmd: 'divide'
    , meta$: {
        user: {
          superuser: true  // always authorized
        }
      }
    }, function(err, res) {
      console.log('success!')
    })

    Permissions

    Permissions allow you to specify an arbitry level of granularity from 1 level to as deep as you wish to go. Giving the user object a nested permissions object will dictate what a user has access to. The terminal key in the object tree should be a boolean value (true or false). The absence of a key is equivelent to false

    const user = {
      roles: ['grunt']
    , permissions: {
        auth: {
          user: {
            create: true
          , read: true
          , update: true
          , delete: false
          }
        }
      , blog: {
          post: {
            create: true
          , update: true
          , read: true
          , delete: true
          }
        , tag: {
            read: true
          }
        }
      }
    }

    To mark a handler with the desired permission include a permissions key to the auth object.

    hemera.add({
      topic: 'blog'
    , cmd: 'post'
    , auth$: {
        permissions: 'blog:post:create' // need to permission to create blog posts
      }
    }, function(req, cb) {
      console.log(this.user$)
      cb(null, true)
    })
     
    hemera.add({
      topic: 'user'
    , cmd: 'delete'
    , auth$: {
        permissions: 'one:very:very:specific:perm:only:few:people:have' // very granular permission
      }
    }, function(req, cb) {
      console.log(this.user$)
      cb(null, true)
    })
     
    hemera.add({
      topic: 'internal'
    , cmd: 'dangerous'
    , auth$: {
        permissions: ' '  // super user only access (empty string)
      }
    }, function(req, cb) {
      console.log(this.user$)
      cb(null, true)
    })
    Calling with permissions
    hemera.act({
      topic: 'math'
    , cmd: 'add'
    , meta$: {
        user: {
          permissions: {
            auth: {
              user: {
                create: true
              }
            }
          , one: {
              very: {
                very: {
                  specific: {
                    perm: {
                      only: {
                        few: {
                          people: {
                            have: true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }, function(err, res) {
      console.log(res)
    })

    Install

    npm i @allstar/hemera-permission

    DownloadsWeekly Downloads

    2

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    6.99 kB

    Total Files

    4

    Last publish

    Collaborators

    • esatterwhite