papers_please 0.0.1.beta → 0.0.2.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6a205acbfa3b9735fe92e5f28fd20d692f95d05f
-  data.tar.gz: c4811ebdf8979ecdec29dc11b442daf1b053ba89
+SHA256:
+  metadata.gz: d12ab3dd8981fb3a6fb74a02b0f34e917438792c2151562c9945a04c79d50d9d
+  data.tar.gz: 694b9b96b9057e122392a2382488bfbecc877b881cf681e07dcb066091d2bd8c
 SHA512:
-  metadata.gz: 8ba41bdb2ac002fc19ff9166e92a9e6b7da129f9470251ed2e76db24f497fc5c51afa94d8953832527be4ef5267b547e0798bdf0e6a847b682b1fd87896f3b9f
-  data.tar.gz: 54c2475662d529ad39c63468351f1f8a261471998119983a2249e5cebb82859b320b95f28653450943806dfcd3158adffb3c9e7e135f9bf4ad2e9679e8da34c9
+  metadata.gz: 80a53cd2301779d6a332c1c01d495f54035886d64a5d3d23e3434de008b5fac367e9a351eb96ef1a842b9c1ae4207045c28c739a43d0f3e78def7e7836f65680
+  data.tar.gz: cc6193a203effc3bff3f3351359550ac71fcf4ca83bd1d1f0cd31ed918f2a083c410638e9c6c2e2e1fd2ea21da3cb7555c57a34f3118bf8c5472a5d35e72abdb

data/.byebug_history

@@ -0,0 +1,60 @@
+q
+@policy
+q
+permission
+c
+permission
+c
+permission
+c
+permission
+q
+res.include?(obj)
+posts.include?(obj)
+posts.include(obj)
+res
+obj
+c
+obj
+res.include?(obj)
+res.include?
+res
+c
+u.posts
+u
+c
+u
+c
+role
+q
+role
+q
+applicable_roles.count
+applicable_roles
+c
+q
+@user
+role.applies_to?(@user)
+role
+c
+q
+applicable_roles
+c
+q
+klass
+action
+permissions
+permission_exists?(action, klass)
+action
+q
+n
+s
+actions
+c
+n
+role
+c
+n
+roles.key?(:admin)
+roles
+name

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    papers_please (0.0.1.beta)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    byebug (10.0.2)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    json (2.1.0)
+    rake (10.5.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  byebug
+  papers_please!
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  simplecov
+
+BUNDLED WITH
+   1.16.1

data/README.md

@@ -2,7 +2,98 @@
 
 A roles and permissions gem from Apsis Labs.
 
-**NOTE**: Still under heavy development, definitely not suitable for anything remotely resembling production usage.
+**NOTE**: Still under heavy development, definitely not suitable for anything remotely resembling production usage. Very unlikely to even work.
+
+## Example
+
+```ruby
+# app/policies/access_policy.rb
+class AccessPolicy < PapersPlease::Policy
+  config do
+    # Define a role in a block
+    role :admin, (proc { |u| u.admin? }) do
+      grant [:manage, :archive], Post
+    end
+
+    # Define a role in a class
+    role :member, MemberRole
+
+    # Define a role with no predicate
+    role :guest do
+      grant [:read], Post, predicate: (proc { |u, post| !post.archived? })
+    end
+  end
+end
+
+# app/policies/roles/member_role.rb
+class MemberRole < PapersPlease::Role
+  predicate { |user| user.member? }
+
+  config do
+    grant :create, Post
+    grant [:read, :update], Post, query: (proc { |u| u.posts })
+    grant :archive, Post, query: method(:published_posts)
+  end
+
+  private
+
+  def published_posts(user, klass)
+    user.posts.where(status: :published)
+  end
+end
+
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  # GET /posts
+  def index
+    @posts = policy.query(:read, Post)
+    render json: @posts
+  end
+
+  # GET /posts/:id
+  def show
+    @post = Post.find(params[:id])
+    policy.authorize! :read, @post
+
+    render json: @post
+  end
+
+  # POST /posts/:id/archive
+  def archive
+    @post = Post.find(params[:id])
+    policy.authorize! :archive, @post
+
+    @post.update!(archived: true)
+    render json: @post
+  end
+end
+```
+
+## A helpful CLI
+
+```bash
+$ rails papers_please:roles
+
+# =>
+# | role    | permission | object |
+# | :------ | :--------- | :----- |
+# | :admin  | :create    | Post   |
+# |         | :read      | Post   |
+# |         | :update    | Post   |
+# |         | :destroy   | Post   |
+# |         | :archive   | Post   |
+# |         |            |        |
+# | :member | :create    | Post   |
+# |         | :read      | Post   |
+# |         | :update    | Post   |
+# |         | :archive   | Post   |
+# |         |            |        |
+# | :guest  | :read      | Post   |
+
+$ rails papers_please:annotate [app/policies/access_policy.rb]
+
+# => output roles table to top of AccessPolicy file
+```
 
 ## Installation
 
@@ -24,6 +115,15 @@ Or install it yourself as:
 
 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.
@@ -34,6 +134,10 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/wkirby/papers_please.
 
+## Special Thanks
+
+This owes its existence to [`AccessGranted`](https://github.com/chaps-io/access-granted). Thanks!
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/papers_please/errors.rb

@@ -0,0 +1,11 @@
+module PapersPlease
+  class Error < StandardError; end
+
+  class AccessDenied < Error; end
+
+  class DuplicatePermission < Error; end
+  class InvalidPermission < Error; end
+
+  class DuplicateScope < Error; end
+  class InvalidScope < Error; end
+end

data/lib/papers_please/permission.rb

@@ -0,0 +1,36 @@
+module PapersPlease
+  class Permission
+    attr_accessor :key, :subject, :query, :predicate
+
+    def initialize(key, subject, query: nil, predicate: nil)
+      @key = key
+      @subject = subject
+      @query = query
+      @predicate = predicate
+    end
+
+    def matches?(key, subject)
+      key_matches?(key) && subject_matches?(subject)
+    end
+
+    def granted?(*args)
+      return predicate.call(*args) if predicate.is_a? Proc
+      false
+    end
+
+    def fetch(*args)
+      return query.call(*args) if query.is_a? Proc
+      nil
+    end
+
+    private
+
+    def key_matches?(key)
+      key == @key
+    end
+
+    def subject_matches?(subject)
+      subject == @subject || subject.class <= @subject
+    end
+  end
+end

data/lib/papers_please/policy.rb

@@ -0,0 +1,68 @@
+module PapersPlease
+  class Policy
+    attr_accessor :roles
+    attr_reader :user
+
+    def initialize(user)
+      @user          = user
+      @roles         = {}
+      @cache         = {}
+
+      configure
+    end
+
+    def configure
+      raise NotImplementedError
+    end
+
+    # Add a role to the Policy
+    def add_role(name, predicate = nil, &block)
+      name = name.to_sym
+      raise DuplicateRole if roles.key?(name)
+
+      role = Role.new(name, predicate: predicate, definition: block)
+      roles[name] = role
+
+      role
+    end
+    alias role add_role
+
+    # Look up a stored permission block and call with
+    # the current user and subject
+    def can?(action, subject = nil)
+      applicable_roles.each do |_, role|
+        permission = role.find_permission(action, subject)
+        return permission.granted?(user, subject, action) unless permission.nil?
+      end
+
+      false
+    end
+
+    def cannot?(*args)
+      !can?(*args)
+    end
+
+    def authorize!(action, subject)
+      raise AccessDenied.new(action, subject) if cannot?(action, subject)
+      subject
+    end
+
+    # Look up a stored scope block and call with the
+    # current user and class
+    def scope_for(action, klass)
+      applicable_roles.each do |_, role|
+        permission = role.find_permission(action, klass)
+        return permission.fetch(user, klass, action) unless permission.nil?
+      end
+
+      nil
+    end
+
+    # Fetch roles that apply to the current user
+    def applicable_roles
+      @applicable_roles ||= roles.select do |_, role|
+        role.applies_to?(user)
+      end
+    end
+  end
+end

data/lib/papers_please/role.rb

@@ -0,0 +1,82 @@
+module PapersPlease
+  class Role
+    attr_reader :name, :predicate, :permissions
+
+    def initialize(name, predicate: nil, definition: nil)
+      @name = name
+      @predicate = predicate
+      @permissions = []
+
+      instance_eval(&definition) unless definition.nil?
+    end
+
+    def applies_to?(user)
+      return @predicate.call(user) if @predicate.is_a? Proc
+      true
+    end
+
+    def add_permission(actions, klass, query: nil, predicate: nil)
+      prepare_actions(actions).each do |action|
+        raise DuplicatePermission if permission_exists?(action, klass)
+
+        has_query = query.is_a?(Proc)
+        has_predicate = predicate.is_a?(Proc)
+        permission = Permission.new(action, klass)
+
+        if has_query && has_predicate
+          # Both query & predicate provided
+
+          permission.query = query
+          permission.predicate = predicate
+        elsif has_query && !has_predicate
+          # Only query provided
+
+          permission.query = query
+
+          if action == :create && actions == :manage
+            # If the action is :create, expanded from :manage
+            # then we set the default all predicate
+            permission.predicate = (proc { true })
+          else
+            # Otherwise the default predicate is to check
+            # for inclusion in the returned relationship
+            permission.predicate = (proc { |user, obj|
+              res = query.call(user, klass, action)
+              res.respond_to?(:include?) && res.include?(obj)
+            })
+          end
+        elsif !has_query && has_predicate
+          # Only predicate provided
+
+          permission.predicate = predicate
+        else
+          # Neither provided
+          permission.query = (proc { klass.all })
+          permission.predicate = (proc { true })
+        end
+
+        permissions << permission
+      end
+    end
+    alias grant add_permission
+
+    def find_permission(action, subject)
+      permissions.detect do |permission|
+        permission.matches? action, subject
+      end
+    end
+
+    def permission_exists?(action, subject)
+      !find_permission(action, subject).nil?
+    end
+
+    private
+
+    # Wrap actions, translating :manage into :crud
+    def prepare_actions(action)
+      Array(*[action]).flat_map do |a|
+        a == :manage ? [:create, :read, :update, :destroy] : [a]
+      end
+    end
+  end
+end

data/lib/papers_please/version.rb

@@ -1,3 +1,3 @@
 module PapersPlease
-  VERSION = "0.0.1.beta"
+  VERSION = "0.0.2.beta"
 end

data/lib/papers_please.rb

@@ -1,4 +1,8 @@
-require "papers_please/version"
+require 'papers_please/version'
+require 'papers_please/errors'
+require 'papers_please/policy'
+require 'papers_please/role'
+require 'papers_please/permission'
 
 module PapersPlease
   # Your code goes here...

data/papers_please.gemspec

@@ -24,4 +24,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency 'simplecov'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papers_please
 version: !ruby/object:Gem::Version
-  version: 0.0.1.beta
+  version: 0.0.2.beta
 platform: ruby
 authors:
 - Apsis Labs
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-20 00:00:00.000000000 Z
+date: 2018-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - wyatt@apsis.io
@@ -59,16 +87,22 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".byebug_history"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
 - lib/papers_please.rb
+- lib/papers_please/errors.rb
+- lib/papers_please/permission.rb
+- lib/papers_please/policy.rb
+- lib/papers_please/role.rb
 - lib/papers_please/version.rb
 - papers_please.gemspec
 homepage: http://apsis.io
@@ -91,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: A roles & permissions gem for ruby applications.