papers_please

A roles and permissions gem from Apsis Labs.

NOTE: Still under heavy development, definitely not suitable for anything remotely resembling production usage. Very unlikely to even work.

Example

# app/policies/access_policy.rbclassAccessPolicy < PapersPlease::Policydefconfigure# Define your rolesrole:super,(proc{ |u| u.super?})role:admin,(proc{ |u| u.admin?})role:member,(proc{ |u| u.member?})role:guestpermit:superdo |role|
role.grant[:manage],Userendpermit:admin,:superdo |role|
role.grant[:manage,:archive],Postendpermit:memberdo |role|
role.grant[:create],Postrole.grant[:update,:read],Post,query: (proc{ |u| u.posts})role.grant[:archive],Post,query: (proc{ |u| u.posts}),predicate: (proc{ |u,post| !post.archived?})endpermit:guestdo |role|
role.grant[:read],Post,predicate: (proc{ |u,post| !post.archived?})endpermit:member,:guestdo |role|
role.grant[:read],Attachment,granted_by: [Post,(proc{ |u,attachment| attachment.post})]endendend# app/controllers/posts_controller.rbclassPostsController < ApplicationController# GET /postsdefindex@posts=policy.query(:read,Post)renderjson: @postsend# GET /posts/:iddefshow@post=Post.find(params[:id])policy.authorize!:read,@postrenderjson: @postend# POST /posts/:id/archivedefarchive@post=Post.find(params[:id])policy.authorize!:archive,@post@post.update!(archived: true)renderjson: @postendendclassAttachmentsController < ApplicationController# GET /attachments/:iddefshow@attachment=Attachment.find([:id])policy.authorize!:read,@attachment# => proxied to Post permission checksend_data@attachment.data,type: @attachment.content_typeendend

A helpful CLI

$ rails papers_please:roles
# =># +---------+------------+------------+------------+----------------+-------------------+# | role | subject | permission | has query? | has predicate? | granted by other? |# +---------+------------+------------+------------+----------------+-------------------+# | admin | Post | create | yes | yes | no |# | | Post | read | yes | yes | no |# | | Post | update | yes | yes | no |# | | Post | destroy | yes | yes | no |# | | Attachment | create | yes | yes | no |# | | Attachment | read | yes | yes | no |# | | Attachment | update | yes | yes | no |# | | Attachment | destroy | yes | yes | no |# +---------+------------+------------+------------+----------------+-------------------+# | manager | Post | create | yes | yes | no |# | | Post | read | yes | yes | no |# | | Post | update | yes | yes | no |# | | Post | destroy | yes | yes | no |# | | Attachment | create | yes | yes | yes |# | | Attachment | read | yes | yes | yes |# | | Attachment | update | yes | yes | yes |# | | Attachment | destroy | yes | yes | yes |# +---------+------------+------------+------------+----------------+-------------------+# | member | Post | create | yes | yes | no |# | | Post | read | yes | yes | no |# | | Post | update | yes | yes | no |# | | Attachment | create | yes | yes | yes |# | | Attachment | read | yes | yes | yes |# | | Attachment | update | yes | yes | yes |# +---------+------------+------------+------------+----------------+-------------------+

Installation

Add this line to your application's Gemfile:

gem'papers_please'

And then execute:

$ bundle

Or install it yourself as:

$ gem install papers_please

Usage

TODO: Write usage instructions here

Theory

The structure of papers_please is very simple. At its core, it is a mechanism for storing and retrieving Procs. In an authorization context, these Procs answer two questions:

1. Given a specific user and a specific permission, which objects am I allowed to operate on?
2. Given a specific user and a specific object, do I have a specific permission?

The machinery of papers_please tries to simplify the organization and subsequent access to these questions as much as possible.

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.

Releasing

Create a release from main:

bin/release {major|minor|patch|pre}
git push --follow-tags

The release script validates the repository, bumps the version, creates a git tag.

Publishing to RubyGems and creating a GitHub Release are handled automatically by GitHub Actions.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wkirby/papers_please.

Special Thanks

This owes its existence to AccessGranted. Thanks!

License

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

---

Built by Apsis

papers_please was built by Apsis Labs. We love sharing what we build! Check out our other libraries on Github, and if you like our work you can hire us to build your vision.