Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/davydovanton/kan
Simple, functional authorization library and role management for ruby
https://github.com/davydovanton/kan
authorization kan roles ruby
Last synced: 30 days ago
JSON representation
Simple, functional authorization library and role management for ruby
- Host: GitHub
- URL: https://github.com/davydovanton/kan
- Owner: davydovanton
- License: mit
- Created: 2018-01-01T14:34:36.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2020-03-12T16:30:17.000Z (almost 5 years ago)
- Last Synced: 2024-10-30T05:57:25.070Z (about 1 month ago)
- Topics: authorization, kan, roles, ruby
- Language: Ruby
- Homepage: http://www.kanrb.org
- Size: 102 KB
- Stars: 232
- Watchers: 7
- Forks: 12
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-hanami - kan - Simple, light and functional authorization library (Hanami Gem List / Authorization)
README
# Kan
[](https://travis-ci.org/davydovanton/kan)
[](#backers)
[](#sponsors)
Simple functional authorization library for ruby. Inspired by [transproc](https://github.com/solnic/transproc) and [dry project](http://dry-rb.org)
## Table of context
* [Installation](#installation)
* [Usage](#usage)
* [Contributing](#contributing)
* [License](#license)
* [Code of Conduct](#code-of-conduct)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'kan'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install kan
## Usage
See [User Documentation page](http://kanrb.org/)
* [Basic Usage](http://kanrb.org/basic_usage)
* [Roles](http://kanrb.org/roles)
* [Testing](http://kanrb.org/testing)
* [Dry integration](http://kanrb.org/working_with_dry)
* [F.A.Q.](http://kanrb.org/faq)
## Basic Usage
### Register abilities
```ruby
class Post::Abilities
include Kan::Abilities
register('read') { |_, _| true }
register('edit') { |user, post| user.id == post.user_id }
register('delete') { |_, _| false }
end
```
Also, you can register more than one ability in one place and use string or symbol keys:
```ruby
class Post::AdminAbilities
include Kan::Abilities
register(:read, :edit, :delete) { |user, _| user.admin? }
end
class Comments::Abilities
include Kan::Abilities
register('read') { |_, _| true }
register('edit') { |user, _| user.admin? }
register(:delete) do |user, comment|
user.id == comment.user_id && comment.created_at < Time.now + TEN_MINUTES
end
end
```
### Check abilities
```ruby
abilities = Kan::Application.new(
post: Post::Abilities.new,
comment: Comments::Abilities.new
)
abilities['post.read'].call(current_user, post) # => true
abilities['post.delete'].call(current_user, post) # => false
abilities['comment.delete'].call(current_user, post) # => false
```
#### Default ability block
By default Kan use `proc { true }` as a default ability block:
```ruby
abilities['comment.invalid'].call(current_user, post) # => true
```
But you can rewrite it
```ruby
admin_abilities = Kan::Application.new(
post: Post::AdminAbilities.new(default_ability_block: proc { false }),
comment: Comments::Abilities.new,
)
admin_abilities['post.delete'].call(current_user, post) # => false
admin_abilities['post.delete'].call(admin_user, post) # => true
admin_abilities['post.invalid'].call(current_user, post) # => false
```
#### List of abilities
You can provide array of abilities for each scope and Kan will return `true` if at least one ability return `true`:
```ruby
global_abilities = Kan::Application.new(
post: [Post::Abilities.new, Post::AdminAbilities.new],
comment: Comments::Abilities.new
)
global_abilities['post.edit'].call(current_user, post) # => false
global_abilities['post.edit'].call(owner_user, post) # => true
global_abilities['post.edit'].call(admin_user, post) # => true
```
### Aliases
You can use strings or symbols and then use it as name of ability
```ruby
class Post::Abilities
include Kan::Abilities
register(:edit) { |_, _| true }
register_alias(:correct, 'edit')
end
abilities = Kan::Application.new(
post: Post::Abilities.new
)
abilities['post.correct'].call(current_user, post) # => true
```
### Callback
You can provide callable object (that respond to #call) that accepts ability_name and payload params to `after_call_callback` param of your ability:
```ruby
admin_abilities = Kan::Application.new(
post: Post::AdminAbilities.new(after_call_callback: -> (ability_name, payload) { ... }),
comment: Comments::Abilities.new,
)
admin_abilities['post.read'].call(current_user, post) # => false
```
Your object will be executed after calling ability.
## Contributing
### Code and features
Bug reports and pull requests are welcome on GitHub at https://github.com/davydovanton/kan. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
### Docs
Just send PR with changes in `docs/` folder.
### How to instal the project
Just clone repository and call:
```
$ bundle install
$ bundle exec rspec
```
## Contributors
This project exists thanks to all the people who contribute.
## Backers
Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/kan#backer)]
## Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/kan#sponsor)]
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
Everyone interacting in the Kan project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/davydovanton/kan/blob/master/CODE_OF_CONDUCT.md).