Passpartu - changelog

Passpartu makes policies great again (works awesome with Pundit).

Tested with ruby:

• 3.1.1
• 3.0.0
• 2.7.3

Instead of this:

classPostPolicy < ApplicationPolicydefupdate?user.super_admin? || user.admin? || user.manager? || user.supervisor?endend

just this:

classPostPolicy < ApplicationPolicydefupdate?user.can?(:post,:update)endend

Usage

Include Passpartu into your policy model.

classUserincludePasspartuend

NOTE: Your User model must respond to role method that returns a string or a symbol!

Keep all your policies in one place. Create ./config/passpartu.yml and start writing your policies.

Example of passpartu.yml

# ./config/passpartu.ymlmanager: &managerorder:
create: trueedit: truedelete: falseproduct:
create: trueedit: truedelete: false# yaml files supports inheritance!admin:
<<: *managerpost:
create: falseupdate: truedelete: trueorder:
create: trueedit: truedelete: trueproduct:
create: falseedit: truedelete: trueitems: crud: truedelete: false

Features

CRUD

It's possible to use crud key to set values for create, read, update, delete at once. create, read, update, delete has higher priority than crud

In case crud: true and delete: false - result false

Only

It's possible to include specific roles to checks

user_admin.can?(:orders,:edit)# check policy for admin and returns true if policy trueuser_admin.can?(:orders,:edit,only: :admin)# returns true because the user is an admin and we included only adminuser_manager.can?(:orders,:edit,only: :admin)# returns false because user is manager and we included only admin

It's possible to give an array as only attribute

user_admin.can?(:orders,:edit,only: [:admin,:manager])# returns trueuser_manager.can?(:orders,:edit,only: [:admin,:manager])# returns true

Note: only has higher priority than except/skip. Do not use both.

user_admin.can?(:orders,:edit,only: :admin,except: :admin)# returns true

Skip (except)

It's possible to exclude roles from checks

user_admin.can?(:orders,:edit)# check policy for admin and returns true if policy trueuser_admin.can?(:orders,:edit,except: :admin)# returns false because user is admin and we excluded admin

It's possible to give an array as except attribute

user_admin.can?(:orders,:edit,except: [:admin,:manager])# returns falseuser_manager.can?(:orders,:edit,except: [:admin,:manager])# returns false

skip alias to except

Note: expect has higher priority than skip. Do not use both.

user_agent.can?(:orders,:edit,except: [:admin,:manager]){user_agent.orders.include?(order)}# equals touser_agent.can?(:orders,:edit,skip: [:admin,:manager]){user_agent.orders.include?(order)}

Per role methods

Check user roles AND policy rule

# check if user admin AND returns true if policy trueuser_admin.admin_can?(:orders,:edit)# true# check if user manager AND returns true if policy trueuser_admin.manager_can?(:orders,:edit)# false

Code blocks

# check rules as usual AND code in the block user_agent.can?(:orders,:edit,except: [:admin,:manager]){user_agent.orders.include?(order)}# OR user_agent.agent_can?(:orders,:edit,except: [:admin,:manager]){user_agent.orders.include?(order)}

'Maybe' option

Option 'maybe' means that user can do something if the block returns true. In this case block is required and error is raised when option is maybe and no block given.

manager:
products:
create: truedelete: falsebookings:
update: maybe

manager.can?(:bookings,:update)# raises errormanager.can?(:bookings,:update){user.bookings.include?(booking)}# returns true or false

Waterfall check

Allow or restrict absolutely everything for particular role or/and particular domain.

# ./config/initializers/passpartu.rbPasspartu.configuredo |config|
config.check_waterfall=trueend

# ./config/passpartu.ymlsuper_admin: truesuper_looser: falsemedium_looser:
orders:
create: truedelete: falseproducts: true

user_super_admin.can?(:do,:whatever,:want)# trueuser_super_loser.can?(:do,:whatever,:want)# falseuser_medium_loser.can?(:orders,:create)# trueuser_medium_loser.can?(:orders,:delete)# falseuser_medium_loser.can?(:products,:create)# trueuser_medium_loser.can?(:products,:create,:and_delete)# true

Real life example

You need to check custom rule for agent

# ./config/passpartu.ymladmin:
order:
create: trueedit: truedelete: truemanager:
order:
create: trueedit: truedelete: falseagent:
order:
create: trueedit: truedelete: false

user.can?(:order,:edit,except: :agent) || user.agent_can?(:order,:edit){user.orders.include?(order)}

1. This code returns true if user is admin or manager
2. This code returns true if user is agent AND if agent policy set to true AND if given block returns true

Configuration

You can configure Passpartu by creating ./config/initializers/passpartu.rb.

Default configs are:

Passpartu.configuredo |config|
config.policy_file='./config/passpartu.yml'config.raise_policy_missed_error=trueconfig.check_waterfall=falseconfig.role_access_method=:roleend

Raise policy missed errors

By default Passpartu will raise an PolicyMissedError if policy is missed in passpartu.yml. In initializer set config.raise_policy_missed_error = false in order to return false in case when policy is not defined. This is a good approach to write only "positive" policies (only true) and automatically restricts everything that is not mentioned in passpartu.yml

Installation

Add this line to your application's Gemfile:

gem'passpartu'

And then execute:

$ bundle

Or install it yourself as:

$ gem install passpartu

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/coaxsoft/passpartu. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Passpartu project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Idea

Initially designed and created by Orest Falchuk