Neutral, Plus or Minus

    axesor
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.8 • Public • Published

    Build Status Coverage Maintainability Vulnerabilities Dependency Status Dev Dependency Status

    Axesor

    Axesor is tiny package for working with ACLs. Axesor using the accesscontrol package.

    GitHub repository: https://github.com/AckeeCZ/axesor

    Install

    npm i --save axesor

    Usage

    import { Acl } from 'axesor';
    
    // define all your grants
    const grants = {
        admin: {
            video: {
                'create:any': ['*', '!views'],
                'read:any': ['*'],
                'update:any': ['*', '!views'],
                'delete:any': ['*']
            }
        },
        user: {
            video: {
                'create:own': ['*', '!rating', '!views'],
                'read:own': ['*'],
                'update:own': ['*', '!rating', '!views'],
                'delete:own': ['*']
            }
        }
    };
    
    // define options
    const options = {
        getRoles: (user) => user.roles,     // required - return string[]
        logger: console,                    // optional
        ownerFunctions: {                   // optional - here you can specify ownership between resources
            video: (user, video) => user.id === video.userId,
        },
    };
    
    const ac = new Acl(grants, options);
    // user = logged user
    // .read(video, 'video')
    //      - first argument is resource (for example row from database)
    //      - second argument is string key - name of the resource you define in grants object
    // returns
    //      - granted: boolean      - if user is granted to read
    //      - action: string        - read, create, update, delete
    //      - roles: string[]       - user roles
    //      - resource: string      - resource string key representation from grants object
    //      - attributes: string[]  - JSON path string array of resource fields which user is allowed to read / update / create / delete - array of fields which you define in grants object
    const permission = ac.can(user).read(video, 'video'); // .create(), .update(), .delete() with same arguments
    // you can use filter function to filter fields from resource which user can manipulate with
    // this function filters recursively
    const allowedVideo = permission.filter(video);

    Custom rules

    • You can define custom rules, these functions are called always when you are calling one of the read / update / create / delete functions
    • Custom rules returns inside the attributes field only [] or ['*'] - not allowed or allowed with all grants
    • Arguments:
      1. action - read / update / create / delete
      2. resource type - string resource key which you define in grants object
      3. custom function - with logged user and resource object, it must return boolean or you can throw an error
    • If rule is defined for some action and resource, the function will be called always when you call ac.can(user).read(booking, 'bookings') for example
    • Custom rules have greater importance then ownerFunctions, these functions will be called firstly
    import { Acl, Action } from 'axesor';
    
    const ac = new Acl({}, {}); // todo
    
    ac.addRule(Action.update, 'bookings', (user, booking) => {
        if ((user.roles.includes('partner') && user.partnerId === booking.partnerId)
            || user.roles.includes('admin')) {
            return true;
        }
        throw new Error('You are not allowed to edit this booking');
    });
    ac.addRule(Action.update, 'bookings', (user, booking) => {
        if (booking.state === 'closed' && !user.roles.includes('admin')) {
            throw new Error('You are not allowed to edit closed booking');
        }
        return true;
    });

    Role inheritance

    Create a role hierarchy via inheritance.

    import { Acl, Action } from 'axesor';
    
    const grants = {
        admin: {
            rocket: {
                'create:any': ['*'],
                'read:any': ['*'],
                'update:any': ['*'],
                'delete:any': ['*'],
            }
        },
        user: {
            bike: {
                'create:any': ['*'],
                'read:any': ['*'],
                'update:any': ['*'],
                'delete:any': ['*'],
            }
        }
    };
    
    const inheritance: {
        // admin extends user --> can manage rockets and bikes
        admin: 'user',
        // can also inherit multiple: admin: ['user']
    }
    
    const ac = new Acl(grants, { inheritance, // todo });
    // alternatively add via method
    const ac = new Acl(grants, { // todo });
    ac.addRoleInheritance(inheritance)

    Make sure to reference only roles defined in grants object. For more info, see roles.

    Tests

    npm run test

    License

    This project is licensed under MIT.

    Keywords

    none

    Install

    npm i axesor

    DownloadsWeekly Downloads

    8

    Version

    0.1.8

    License

    MIT

    Unpacked Size

    96.8 kB

    Total Files

    28

    Last publish

    Collaborators

    • ackeecz