accession 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b50e72cd40d55893e6df819c563697cee1a9cbc
-  data.tar.gz: 5b2132715da7cf3b472ec9e71877e6eaac0f74d6
+  metadata.gz: cb353f66be2c532cd4844fd2a692110de2102da3
+  data.tar.gz: 5fc8432f27dfbee0601990130d913cc686d308bf
 SHA512:
-  metadata.gz: 3065baf79181f916f4a4f65b8b1f5fb6ab78e19b56b271d495d68c0fe800f55dbfcf7f0669ebfaac21542d6135b2749dc6a55c95f2d1ab618a731ccbf1f66c96
-  data.tar.gz: 56671e12ef974a283796eab91c00f90d27d30f33ddf09cbe29caeeb2f484c94bb516a8f1c1862ce1d4cdd58dcba6bd29f5ab1aa7abe02f5c0c6a13cbba383116
+  metadata.gz: ffd2c7b597d75e062d91b66433daf438703e8591e103633c77e4cf77b430e1b070547e271ec8966c1600843df0f4f78ccd82a25aa7d63cd7da3c5e61047aa3a4
+  data.tar.gz: fd69fbe54505d932427cfbed1f0bc6978abe4e072de79d694580bd3df2f576ca7cfd4dc87702c08bf04580bc9fb29db49522158863d1785902b704fe3401912c

data/README.md

@@ -1,6 +1,42 @@
 # Accession
 
-TODO: Write a gem description
+[![Gem Version][GV img]][Gem Version]
+[![Build Status][BS img]][Build Status]
+[![Dependency Status][DS img]][Dependency Status]
+[![Code Climate][CC img]][Code Climate]
+[![Coverage Status][CS img]][Coverage Status]
+
+[Gem Version]: https://rubygems.org/gems/accession
+[Build Status]: https://travis-ci.org/ausaccessfed/accession
+[Dependency Status]: https://gemnasium.com/ausaccessfed/accession
+[Code Climate]: https://codeclimate.com/github/ausaccessfed/accession
+[Coverage Status]: https://coveralls.io/r/ausaccessfed/accession
+
+[GV img]: https://img.shields.io/gem/v/accession.svg
+[BS img]: https://img.shields.io/travis/ausaccessfed/accession/develop.svg
+[DS img]: https://img.shields.io/gemnasium/ausaccessfed/accession.svg
+[CC img]: https://img.shields.io/codeclimate/github/ausaccessfed/accession.svg
+[CS img]: https://img.shields.io/coveralls/ausaccessfed/accession.svg
+
+Extremely lightweight permissions for Ruby applications.
+
+Author: Shaun Mangelsdorf
+
+```
+Copyright 2014-2015, Australian Access Federation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
 
 ## Installation
 
@@ -10,22 +46,92 @@ Add this line to your application's Gemfile:
 gem 'accession'
 ```
 
-And then execute:
+Use Bundler to install the dependency:
+
+```
+bundle install
+```
+
+## Usage
 
-    $ bundle
+Accession is intended to be a lightweight and flexible way to add permissions to
+your model classes. It imposes very few requirements on your application.
 
-Or install it yourself as:
+The two major pieces of API provided by Accession are:
 
-    $ gem install accession
+* The `Accession::Principal` module, which consumes a list of permission strings
+  returned by the `permissions` method in a class and gives a `permits?` method
+  for performing a permission check.
+* The `Accession::Permission.regexp` pattern, which can be used to validate an
+  Accession permission string.
 
-## Usage
+To get started add a `permission` method to your class that represents an
+authenticated user. This method returns permissions strings associated with that
+user. Once you have this method, include the `Accession::Principal` module in
+your class to add the `permits?` method.
+
+An example implementation is:
+
+```ruby
+# app/models/permission.rb
+class Permission < ActiveRecord::Base
+  validates :value, format: Accession::Permission.regexp
+end
+
+# app/models/role.rb
+class Role < ActiveRecord::Base
+  has_many :permissions
+end
+
+# app/models/subject.rb
+class Subject < ActiveRecord::Base
+  include Accession::Principal
+
+  has_and_belongs_to_many :roles
+
+  def permissions
+    roles.flat_map { |role| role.permissions.map(&:value) }
+  end
+end
+```
+
+With this in place, a `Subject` can have a permission check performed, for
+example:
+
+```ruby
+class ProjectsController < ApplicationController
+  before_action { @subject = Subject.find(session[:subject_id]) }
+
+  def index
+    fail('Not allowed') unless @subject.permits?('projects:list')
+  end
+end
+```
+
+## Permission Strings
+
+A permission string is comprised of one or more colon-separated parts that
+describe the action being permitted. Each part of the permission string can be
+either a wildcard (`*`), or a "word" of characters `a-z A-Z 0-9 _ -`
+
+A wildcard in any position will match a single word in that position. A wildcard
+in the last position will match any number of words in the action string.
 
-TODO: Write usage instructions here
+| permission | action  | result |
+|------------|---------|--------|
+| `a`        | `a`     | permit |
+| `a`        | `b`     | deny   |
+| `a:b:c`    | `a:b:c` | permit |
+| `a:b:c`    | `a:b:d` | deny   |
+| `*:b:c`    | `a:b:c` | permit |
+| `a:b:*`    | `a:b:c` | permit |
+| `a:*`      | `a:b:c` | permit |
+| `*:c`      | `a:b:c` | deny   |
+| `*`        | `a:b:c` | permit |
+| `a:b:*`    | `a:b`   | deny   |
+| `a:*:*`    | `a:b`   | deny   |
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/accession/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Refer to [GitHub Flow](https://guides.github.com/introduction/flow/) for
+help contributing to this project.

data/lib/accession/permission.rb

@@ -1,5 +1,14 @@
 module Accession
   class Permission
+    # A segment is a "word" in the url-safe base64 alphabet, or single '*'
+    SEGMENT = /([\w-]+|\*)/.freeze
+    REGEXP = /\A(#{SEGMENT}:)*#{SEGMENT}\z/.freeze
+    private_constant :SEGMENT, :REGEXP
+
+    def self.regexp
+      REGEXP
+    end
+
     def initialize(value)
       @parts = value.split(':')
     end

data/lib/accession/version.rb

@@ -1,3 +1,3 @@
 module Accession
-  VERSION = '0.0.2'
+  VERSION = '1.0.0'
 end

data/spec/lib/accession/permission_spec.rb

@@ -58,5 +58,21 @@ module Accession
       denies('a:b:c:e:d')
       denies('a:b:d:c')
     end
+
+    context '::regexp' do
+      subject { Accession::Permission.regexp }
+
+      it { is_expected.to match('*') }
+      it { is_expected.to match('a:b:c:d') }
+      it { is_expected.to match('a:b:c:*') }
+      it { is_expected.to match('a:b:*:d') }
+      it { is_expected.to match('word:word:word:__________') }
+      it { is_expected.to match('*:*:*:*:*:*:*:*:*:*:*:*:*:*:*:*:*:*:*:*:*:*') }
+      it { is_expected.not_to match('a:b:%') }
+      it { is_expected.not_to match('a:b:%:*') }
+      it { is_expected.not_to match('%') }
+      it { is_expected.not_to match('') }
+      it { is_expected.not_to match("*:*:*:*\n:*:*") }
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: accession
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Shaun Mangelsdorf
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-24 00:00:00.000000000 Z
+date: 2015-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler