blacklight-access_controls 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 715bccb2faf2cc502417ad8d1f9052baf98c2c2e
-  data.tar.gz: c011219a6d76e3c0e6bba5640c9f5c92eb5fe300
+  metadata.gz: e429877da325ab5e409d1d62676ef8d5e1fc0495
+  data.tar.gz: c77b7f0cf4e24cdaa8acfe763e92aacd16b36f64
 SHA512:
-  metadata.gz: d80acc63c003ee2d3b84b5790bd5a755cea409efb58ee4311fd6e5b236712c3fbbb92e9609f6e93e948bc7cfae7bd0938dfad4f51e6d109a603ce3dc4ea4dfdd
-  data.tar.gz: 54dfe0310b6df052616602eb53d0f916e431717f0a918b0d436e992d8ee9eacb03312d5b69de7be2d880f62bfc0ee1d10db2b653c66b60195321790a526cafad
+  metadata.gz: 054afd2481955b5278a523a11d57723b0d1c8b6fe27d18e5956abae262b2d93ed77e9775b0ad582f70d73269d4e9c69a3c790a5aa5b0e7884e59db2a918c9523
+  data.tar.gz: d679058bc3c0aa1a782f992433678e229f10d892e81257dfe9329601dcfefaeb0db3af6e579706781a9393ae30f48725c7b9b6f5b1e21035269182b974a200f2

data/README.textile

@@ -21,20 +21,65 @@ h3. Configure solr
 h3. Run the generator
 
 <pre>
-rails generate blacklight:access_controls
+  rails generate blacklight:access_controls
 </pre>
 
+If you want to use a different user model than "User", you can pass an argument to the generator
+
+<pre>
+  rails generate blacklight:access_controls -m Student
+</pre>
+
+If you have more than one search builder class, or if your search builder is located someplace other than app/models/search_builder.rb, you can pass an argument to the generator
+
+<pre>
+  rails generate blacklight:access_controls -b app/search_builders/search_one.rb app/search_builders/search_two.rb
+</pre>
+
+h3. Implement user.groups
+
+* If you are using LDAP or some other way of controlling group-level access to records, implement a 'groups' method on your User model.  If you call user.groups method on a user, it should return a list of groups that the user belongs to.
+
 
 h2. Using Access Controls
 
 Some notes about using blacklight-access_controls within your Blacklight app:
 
-* You can grant access to a record to specific users or groups by adding them to the correct fields in the solr document.  For example, discover_access_group_ssim: "public" or read_access_person_ssim: "frodo@example.com".
+* Blacklight Access Controls allows 3 types of access to a record:  discover, read, or download.  Of course, you can change or redefine the meaning of these access levels in your own app, but within the context of blacklight-access_controls, the 3 levels of access mean this:
+** Discover access allows the user to see that a record does exist and view minimal metadata about the record, but the user may not be allowed to read or download the full record. (e.g. The user can see the record in a search results list, but if they visit the show page of the record, they will be denied access.)
+** Read access allows the user to view the entire record, but the user might not be able to download attached files.
+** Download access allows the user to download the full record and/or files that are attached to the record.
+
+* The access levels are hierarchical, so if you grant "download" access to a user, the user will automatically be granted "read" and "discover" access.  If you grant "read" access, the user will also have "discover" access, but not "download" access.
+
+* You can grant access to a record to specific users or groups by adding them to the correct fields in the solr document.  For example:
+
+<pre>
+  {
+    discover_access_group_ssim: "public",
+    read_access_person_ssim: "bilbo@example.com",
+    download_access_person_ssim: "frodo@example.com"
+  }
+</pre>
 
 * The gem expects user.groups to return a list of groups that the user belongs to.  By default, all users belong to a group called "public", and all logged-in users belong to a group called "registered".
 
 * If you want a record to be readable by the public, you need to add "public" to the "read_access_group_ssim" field in the solr document, or if you want discover-only access, add "public" to "discover_access_group_ssim".  (Discover-only means that the user can see that the record exists in a catalog search, but won't be able to view the record itself.)
 
+* If you grant download access to a user or group, blacklight-access_controls will grant access only to the SolrDocument.  If you want the user to be able to download a different type of object such as an attached file, you may need to add that permission into your cancan abilities.  In this example, we check the permissions of the user id for the object itself, instead of for the SolrDocument that indexes the object:
+
+<pre>
+  can :download, AttachedFile, parent: { user_id: user.id }
+</pre>
+
+* If you want to test download access against the solr document instead of against the object (for example, to decide whether or not to display a download link on an index or show page), then you can just add a normal cancan check in your controller or view.  There is no need to add anything special to the cancan ability class.
+
+<pre>
+  if can? :download, solr_document
+    # do something
+  end
+</pre>
+
 
 h2. Developer Notes
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/blacklight/access_controls.rb

@@ -6,7 +6,6 @@ module Blacklight
     autoload :User
     autoload :PermissionsQuery
     autoload :PermissionsCache
-    autoload :PermissionsSolrDocument
     autoload :Ability
     autoload :Enforcement
     autoload :Catalog

data/lib/blacklight/access_controls/ability.rb

@@ -11,9 +11,9 @@ module Blacklight
 
         # Once you include this module, you can add custom
         # permission methods to ability_logic, like so:
-        # self.ability_logic +=[:setup_my_permissions]
+        # self.ability_logic += [:setup_my_permissions]
         class_attribute :ability_logic
-        self.ability_logic = [:discover_permissions, :read_permissions]
+        self.ability_logic = [:discover_permissions, :read_permissions, :download_permissions]
       end
 
       def initialize(user, options={})
@@ -63,6 +63,17 @@ module Blacklight
         end
       end
 
+      def download_permissions
+        can :download, String do |id|
+          test_download(id)
+        end
+
+        can :download, SolrDocument do |obj|
+          cache.put(obj.id, obj)
+          test_download(obj.id)
+        end
+      end
+
       def test_discover(id)
         Rails.logger.debug("[CANCAN] Checking discover permissions for user: #{current_user.user_key} with groups: #{user_groups.inspect}")
         group_intersection = user_groups & discover_groups(id)
@@ -75,6 +86,12 @@ module Blacklight
         !group_intersection.empty? || read_users(id).include?(current_user.user_key)
       end
 
+      def test_download(id)
+        Rails.logger.debug("[CANCAN] Checking download permissions for user: #{current_user.user_key} with groups: #{user_groups.inspect}")
+        group_intersection = user_groups & download_groups(id)
+        !group_intersection.empty? || download_users(id).include?(current_user.user_key)
+      end
+
       # You can override this method if you are using a different AuthZ (such as LDAP)
       def user_groups
         return @user_groups if @user_groups
@@ -108,22 +125,40 @@ module Blacklight
         dp
       end
 
+      # download access implies read access, so read_groups is the union of download and read groups.
       def read_groups(id)
         doc = permissions_doc(id)
         return [] if doc.nil?
-        rg = Array(doc[self.class.read_group_field])
+        rg = download_groups(id) | Array(doc[self.class.read_group_field])
         Rails.logger.debug("[CANCAN] read_groups: #{rg.inspect}")
         rg
       end
 
+      # download access implies read access, so read_users is the union of download and read users.
       def read_users(id)
         doc = permissions_doc(id)
         return [] if doc.nil?
-        rp = Array(doc[self.class.read_user_field])
+        rp = download_users(id) | Array(doc[self.class.read_user_field])
         Rails.logger.debug("[CANCAN] read_users: #{rp.inspect}")
         rp
       end
 
+      def download_groups(id)
+        doc = permissions_doc(id)
+        return [] if doc.nil?
+        dg = Array(doc[self.class.download_group_field])
+        Rails.logger.debug("[CANCAN] download_groups: #{dg.inspect}")
+        dg
+      end
+
+      def download_users(id)
+        doc = permissions_doc(id)
+        return [] if doc.nil?
+        dp = Array(doc[self.class.download_user_field])
+        Rails.logger.debug("[CANCAN] download_users: #{dp.inspect}")
+        dp
+      end
+
       module ClassMethods
 
         def discover_group_field
@@ -142,6 +177,14 @@ module Blacklight
           Blacklight::AccessControls.config.read_user_field
         end
 
+        def download_group_field
+          Blacklight::AccessControls.config.download_group_field
+        end
+
+        def download_user_field
+          Blacklight::AccessControls.config.download_user_field
+        end
+
       end
     end
   end

data/lib/blacklight/access_controls/config.rb

@@ -4,15 +4,21 @@ module Blacklight
 
       def initialize
         @user_model = default_user_model
+
         @discover_group_field = default_discover_group_field
         @discover_user_field = default_discover_user_field
+
         @read_group_field = default_read_group_field
         @read_user_field = default_read_user_field
+
+        @download_group_field = default_download_group_field
+        @download_user_field = default_download_user_field
       end
 
       attr_accessor :user_model
       attr_accessor :discover_group_field, :discover_user_field
       attr_accessor :read_group_field, :read_user_field
+      attr_accessor :download_group_field, :download_user_field
 
       def default_user_model
         'User'
@@ -34,6 +40,14 @@ module Blacklight
         "read_access_person_ssim"
       end
 
+      def default_download_group_field
+        "download_access_group_ssim"
+      end
+
+      def default_download_user_field
+        "download_access_person_ssim"
+      end
+
     end
   end
 end

data/lib/blacklight/access_controls/permissions_query.rb

@@ -12,7 +12,7 @@ module Blacklight::AccessControls
     end
 
     def permissions_document_class
-      Blacklight::AccessControls::PermissionsSolrDocument
+      SolrDocument
     end
 
     protected

data/lib/generators/blacklight/access_controls_generator.rb

@@ -11,18 +11,29 @@ module Blacklight
 
     source_root File.expand_path("..", __FILE__)
 
+    class_option :user_model, aliases: '-m',
+      type: :string, default: 'User',
+      desc: "What is your user model called?"
+
+    class_option :search_builders, aliases: '-b', type: :array,
+      default: Array(File.join('app', 'models', 'search_builder.rb')),
+      desc: "The path(s) to your search builder model(s)"
+
+
     def add_access_controls_to_user
-      say_status('status', 'ADD ACCESS CONTROLS TO USER', :yellow)
-      insert_into_file 'app/models/user.rb',
+      say_status('status', 'ADDING ACCESS CONTROLS TO USER MODEL', :yellow)
+      insert_into_file File.join('app','models', "#{options[:user_model].underscore}.rb"),
         "  include Blacklight::AccessControls::User\n\n",
         after: "include Blacklight::User\n"
     end
 
     def add_access_controls_to_search_builder
-      say_status('status', 'ADDING ACCESS CONTROLS TO SEARCH BUILDER', :yellow)
-      insert_into_file 'app/models/search_builder.rb',
-        "  include Blacklight::AccessControls::Enforcement\n",
-        before: "end"
+      say_status('status', 'ADDING ACCESS CONTROLS TO SEARCH BUILDERS', :yellow)
+      options[:search_builders].each do |file_path|
+        insert_into_file file_path,
+          "  include Blacklight::AccessControls::Enforcement\n\n",
+          after: "include Blacklight::Solr::SearchBuilderBehavior\n"
+      end
     end
 
     def add_access_controls_to_catalog_controller

data/solr_conf/conf/solrconfig.xml

@@ -317,14 +317,12 @@
         access_ssim,
         discover_access_group_ssim,discover_access_person_ssim,
         read_access_group_ssim,read_access_person_ssim,
-        edit_access_group_ssim,edit_access_person_ssim,
+        download_access_group_ssim,download_access_person_ssim,
         depositor_ti,
-        embargo_release_date_dtsi
         inheritable_access_ssim,
         inheritable_discover_access_group_ssim,inheritable_discover_access_person_ssim,
         inheritable_read_access_group_ssim,inheritable_read_access_person_ssim,
-        inheritable_edit_access_group_ssim,inheritable_edit_access_person_ssim,
-        inheritable_embargo_release_date_dtsi
+        inheritable_download_access_group_ssim,inheritable_download_access_person_ssim,
       </str>
     </lst>
   </requestHandler>

data/spec/unit/ability_spec.rb

@@ -10,6 +10,8 @@ describe Ability do
       expect(Ability.read_user_field).to eq 'read_access_person_ssim'
       expect(Ability.discover_group_field).to eq 'discover_access_group_ssim'
       expect(Ability.discover_user_field).to eq 'discover_access_person_ssim'
+      expect(Ability.download_group_field).to eq 'download_access_group_ssim'
+      expect(Ability.download_user_field).to eq 'download_access_person_ssim'
     end
   end
 
@@ -23,6 +25,7 @@ describe Ability do
 
       it { should     be_able_to(:discover, asset) }
       it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
     end
 
     context "Then a registered user" do
@@ -31,6 +34,7 @@ describe Ability do
 
       it { should     be_able_to(:discover, asset) }
       it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
     end
 
     context 'With an ID instead of a SolrDocument' do
@@ -45,6 +49,7 @@ describe Ability do
       # It should still work, even if we just pass in an ID
       it { should     be_able_to(:discover, asset.id) }
       it { should_not be_able_to(:read, asset.id) }
+      it { should_not be_able_to(:download, asset.id) }
     end
   end
 
@@ -52,12 +57,52 @@ describe Ability do
     let(:asset) { SolrDocument.new(id: 'public_read',
                   read_access_group_ssim: ['public']) }
 
+    context "Then a not-signed-in user" do
+      let(:user) { nil }
+      subject { ability }
+
+      it { should     be_able_to(:discover, asset) }
+      it { should     be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
+    end
+
+    context "Then a registered user" do
+      let(:user) { create(:user) }
+      subject { ability }
+
+      it { should     be_able_to(:discover, asset) }
+      it { should     be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
+    end
+
+    context 'With an ID instead of a SolrDocument' do
+      let(:user) { create(:user) }
+      subject { ability }
+
+      let(:asset) {
+        create_solr_doc(id: 'public_read',
+                        read_access_group_ssim: ['public'])
+      }
+
+      # It should still work, even if we just pass in an ID
+      it { should     be_able_to(:discover, asset.id) }
+      it { should     be_able_to(:read, asset.id) }
+      it { should_not be_able_to(:download, asset.id) }
+    end
+  end
+
+  describe "Given an asset that has been made publicly downloadable" do
+    let(:id) { 'public_download' }
+    let(:asset) { SolrDocument.new(id: id,
+                    download_access_group_ssim: ['public']) }
+
     context "Then a not-signed-in user" do
       let(:user) { nil }
       subject { ability }
 
       it { should be_able_to(:discover, asset) }
       it { should be_able_to(:read, asset) }
+      it { should be_able_to(:download, asset) }
     end
 
     context "Then a registered user" do
@@ -66,23 +111,26 @@ describe Ability do
 
       it { should be_able_to(:discover, asset) }
       it { should be_able_to(:read, asset) }
+      it { should be_able_to(:download, asset) }
     end
 
-    context 'With an ID instead of a SolrDocument' do
+    context 'With an ID instead of a record' do
       let(:user) { create(:user) }
       subject { ability }
 
       let(:asset) {
-        create_solr_doc(id: 'public_read',
-                        read_access_group_ssim: ['public'])
+        create_solr_doc(id: id,
+                        download_access_group_ssim: ['public'])
       }
 
       # It should still work, even if we just pass in an ID
       it { should be_able_to(:discover, asset.id) }
       it { should be_able_to(:read, asset.id) }
+      it { should be_able_to(:download, asset.id) }
     end
   end
 
+
   describe "Given an asset to which a specific user has discovery access" do
     let(:user_with_access) { create(:user) }
     let(:asset) { SolrDocument.new(id: 'user_disco', discover_access_person_ssim: [user_with_access.email]) }
@@ -93,6 +141,7 @@ describe Ability do
 
       it { should_not be_able_to(:discover, asset) }
       it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
     end
 
     context "Then a different registered user" do
@@ -101,6 +150,7 @@ describe Ability do
 
       it { should_not be_able_to(:discover, asset) }
       it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
     end
 
     context "Then that user" do
@@ -109,6 +159,7 @@ describe Ability do
 
       it { should     be_able_to(:discover, asset) }
       it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
     end
   end
 
@@ -122,6 +173,39 @@ describe Ability do
 
       it { should_not be_able_to(:discover, asset) }
       it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
+    end
+
+    context "Then a different registered user" do
+      let(:user) { create(:user) }
+      subject { ability }
+
+      it { should_not be_able_to(:discover, asset) }
+      it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
+    end
+
+    context "Then that user" do
+      let(:user) { user_with_access }
+      subject { ability }
+
+      it { should     be_able_to(:discover, asset) }
+      it { should     be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
+    end
+  end
+
+  describe "Given an asset to which a specific user has download access" do
+    let(:user_with_access) { create(:user) }
+    let(:asset) { SolrDocument.new(id: 'user_read', download_access_person_ssim: [user_with_access.email]) }
+
+    context "Then a not-signed-in user" do
+      let(:user) { nil }
+      subject { ability }
+
+      it { should_not be_able_to(:discover, asset) }
+      it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
     end
 
     context "Then a different registered user" do
@@ -130,6 +214,7 @@ describe Ability do
 
       it { should_not be_able_to(:discover, asset) }
       it { should_not be_able_to(:read, asset) }
+      it { should_not be_able_to(:download, asset) }
     end
 
     context "Then that user" do
@@ -138,6 +223,7 @@ describe Ability do
 
       it { should be_able_to(:discover, asset) }
       it { should be_able_to(:read, asset) }
+      it { should be_able_to(:download, asset) }
     end
   end
 

data/spec/unit/catalog_spec.rb

@@ -33,7 +33,7 @@ describe Blacklight::AccessControls::Catalog do
       # to call "super" and then add more permissions checks
       # after that without having to re-fetch the document.
       it 'returns the permissions doc' do
-        expect(subject).to be_a(Blacklight::AccessControls::PermissionsSolrDocument)
+        expect(subject).to be_a(SolrDocument)
       end
     end
   end

data/spec/unit/config_spec.rb

@@ -66,4 +66,30 @@ describe Blacklight::AccessControls::Config do
     end
   end
 
+  describe '#download_group_field' do
+    subject { config.download_group_field }
+
+    it 'has a default value' do
+      expect(subject).to eq "download_access_group_ssim"
+    end
+
+    it 'can be set to a non-default value' do
+      config.download_group_field = 'something else'
+      expect(subject).to eq 'something else'
+    end
+  end
+
+  describe '#download_user_field' do
+    subject { config.download_user_field }
+
+    it 'has a default value' do
+      expect(subject).to eq "download_access_person_ssim"
+    end
+
+    it 'can be set to a non-default value' do
+      config.download_user_field = 'something else'
+      expect(subject).to eq 'something else'
+    end
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blacklight-access_controls
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chris Beer
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-01 00:00:00.000000000 Z
+date: 2015-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cancancan
@@ -146,7 +146,6 @@ files:
 - lib/blacklight/access_controls/enforcement.rb
 - lib/blacklight/access_controls/permissions_cache.rb
 - lib/blacklight/access_controls/permissions_query.rb
-- lib/blacklight/access_controls/permissions_solr_document.rb
 - lib/blacklight/access_controls/user.rb
 - lib/generators/blacklight/ability.rb
 - lib/generators/blacklight/access_controls_generator.rb

data/lib/blacklight/access_controls/permissions_solr_document.rb

@@ -1,2 +0,0 @@
-class Blacklight::AccessControls::PermissionsSolrDocument < SolrDocument
-end