hyrax-acl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d6daf35ffa5e520d644843770558e98616318e3f46e7ff71ee790ed294e4151
+  data.tar.gz: fa15a23186d21120d9bdaeccf57adf244d51ec64854d4619915ac752c86af120
+SHA512:
+  metadata.gz: 71bac13a9baf582a197e16939e4780514d015effd330c91bb7e583d3393f5cac1acc112f70a86910f78ba28ae33558ee63b599245af0d83e0c2c4bafc0fac8d1
+  data.tar.gz: 4de625e404ce9219d1ea20f2f84b02a88e6abff7037ba8e00cf3e3a1327cfd0957b42e372f6d9e6bafa41a78d762f52321203636104e1c1d08e15620eea24ecf

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,174 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (7.0.3)
+      actionview (= 7.0.3)
+      activesupport (= 7.0.3)
+      rack (~> 2.0, >= 2.2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actionview (7.0.3)
+      activesupport (= 7.0.3)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activemodel (7.0.3)
+      activesupport (= 7.0.3)
+    activemodel-serializers-xml (1.0.2)
+      activemodel (> 5.x)
+      activesupport (> 5.x)
+      builder (~> 3.1)
+    activesupport (7.0.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    builder (3.2.4)
+    concurrent-ruby (1.1.10)
+    crass (1.0.6)
+    declarative (0.0.20)
+    declarative-builder (0.1.0)
+      declarative-option (< 0.2.0)
+    declarative-option (0.1.1)
+    diff-lcs (1.5.0)
+    disposable (0.4.7)
+      declarative (>= 0.0.9, < 1.0.0)
+      declarative-builder (< 0.2.0)
+      declarative-option (< 0.2.0)
+      representable (>= 2.4.0, <= 3.1.0)
+      uber (< 0.2.0)
+    draper (4.0.2)
+      actionpack (>= 5.0)
+      activemodel (>= 5.0)
+      activemodel-serializers-xml (>= 1.0)
+      activesupport (>= 5.0)
+      request_store (>= 1.0)
+      ruby2_keywords
+    dry-configurable (0.15.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.6)
+    dry-container (0.9.0)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 0.13, >= 0.13.0)
+    dry-core (0.7.1)
+      concurrent-ruby (~> 1.0)
+    dry-inflector (0.2.1)
+    dry-logic (1.2.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.5, >= 0.5)
+    dry-struct (1.4.0)
+      dry-core (~> 0.5, >= 0.5)
+      dry-types (~> 1.5)
+      ice_nine (~> 0.11)
+    dry-types (1.5.1)
+      concurrent-ruby (~> 1.0)
+      dry-container (~> 0.3)
+      dry-core (~> 0.5, >= 0.5)
+      dry-inflector (~> 0.1, >= 0.1.2)
+      dry-logic (~> 1.0, >= 1.0.2)
+    erubi (1.10.0)
+    faraday (0.17.5)
+      multipart-post (>= 1.2, < 3)
+    htmlentities (4.3.4)
+    i18n (1.10.0)
+      concurrent-ruby (~> 1.0)
+    ice_nine (0.11.2)
+    json (2.6.2)
+    json-canonicalization (0.3.0)
+    json-ld (3.2.1)
+      htmlentities (~> 4.3)
+      json-canonicalization (~> 0.3)
+      link_header (~> 0.0, >= 0.0.8)
+      multi_json (~> 1.15)
+      rack (~> 2.2)
+      rdf (~> 3.2)
+    link_header (0.0.8)
+    loofah (2.18.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (1.0.0)
+    minitest (5.16.1)
+    multi_json (1.15.0)
+    multipart-post (2.2.3)
+    nokogiri (1.13.6-x86_64-linux)
+      racc (~> 1.4)
+    racc (1.6.0)
+    rack (2.2.3.1)
+    rack-test (2.0.0)
+      rack (>= 1.3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.3)
+      loofah (~> 2.3)
+    railties (7.0.3)
+      actionpack (= 7.0.3)
+      activesupport (= 7.0.3)
+      method_source
+      rake (>= 12.2)
+      thor (~> 1.0)
+      zeitwerk (~> 2.5)
+    rake (13.0.6)
+    rdf (3.2.8)
+      link_header (~> 0.0, >= 0.0.8)
+    rdf-vocab (3.2.1)
+      rdf (~> 3.2, >= 3.2.4)
+    reform (2.5.0)
+      disposable (>= 0.4.2, < 0.5.0)
+      representable (>= 2.4.0, < 3.1.0)
+      uber (< 0.2.0)
+    reform-rails (0.2.3)
+      activemodel (>= 5.0)
+      reform (>= 2.3.1, < 3.0.0)
+    representable (3.0.4)
+      declarative (< 0.1.0)
+      declarative-option (< 0.2.0)
+      uber (< 0.2.0)
+    request_store (1.5.1)
+      rack (>= 1.4)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    ruby2_keywords (0.0.5)
+    thor (1.2.1)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    uber (0.1.0)
+    valkyrie (2.2.0)
+      activemodel
+      activesupport
+      disposable (~> 0.4.5)
+      draper
+      dry-struct
+      dry-types (~> 1.0)
+      faraday (< 1.0)
+      json
+      json-ld
+      railties
+      rdf (~> 3.0, >= 3.0.10)
+      rdf-vocab
+      reform (~> 2.2)
+      reform-rails
+    zeitwerk (2.6.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  rspec
+  valkyrie (~> 2)
+
+BUNDLED WITH
+   2.2.16

data/README.md

@@ -0,0 +1,7 @@
+Hyrax Access Control List
+=========================
+
+
+## License
+
+Apache 2.0

data/hyrax-acl.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hyrax/acl/version'
+
+Gem::Specification.new do |spec|
+  spec.authors       = ["Project Surfliner"]
+  spec.email         = ["tomjohnson@ucsb.edu"]
+  spec.description   = 'Access Control List models and support for Hyrax'
+  spec.summary       = <<-SUMMARY
+  Hyrax Access Control List
+SUMMARY
+
+  spec.homepage      = "http://github.com/samvera-labs/hyrax-acl"
+
+  spec.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR).select { |f| File.dirname(f) !~ %r{\A"?spec\/?} }
+  spec.executables   = spec.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  spec.name          = "hyrax-acl"
+  spec.require_paths = ["lib"]
+  spec.version       = Hyrax::Acl::VERSION
+  spec.license       = 'Apache-2.0'
+  spec.metadata      = { "rubygems_mfa_required" => "true" }
+
+  spec.required_ruby_version = '>= 2.7'
+
+  spec.add_dependency "valkyrie", "~> 2"
+
+  spec.add_development_dependency "rspec"
+end

data/lib/hyrax/acl/access_control.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module Acl
+    ##
+    # A list of permissions pertaining to a specific object.
+    #
+    # `AccessControl`s consist of a set of permissions and an `#access_to`
+    # reference to the object that set governs.
+    #
+    # @see Hyrax::AccessControlList for a low level DSL for managing
+    #   `AccessControl` and `Permission` relationships for `Hyrax::Resource`
+    # @see Hyrax::PermissionManager for `read_groups`/`read_users` style setters
+    #   and getters
+    # @see Hyrax::VisibilityWriter, Hyrax::VisibilityReader for
+    #   "open"/"restricted" style visibility management
+    class AccessControl < Valkyrie::Resource
+      ##
+      # @!attribute [rw] access_to
+      #   Supports query for ACLs at the resource level. Permissions should be
+      #   grouped under an AccessControl with a matching `#access_to` so they can
+      #   be retrieved in batch.
+      #
+      #   @return [Valkyrie::ID] the id of the Resource these permissions apply to
+      # @!attribute [rw] permissions
+      #   @return [Enumerable<Hyrax::Acl::Permission>]
+      attribute :access_to,   Valkyrie::Types::ID
+      attribute :permissions, Valkyrie::Types::Set.of(Hyrax::Acl::Permission)
+
+      ##
+      # A finder/factory method for getting an appropriate ACL for a given
+      # resource.
+      #
+      # @param resource [Valkyrie::Resource]
+      # @param query_service [#find_inverse_references_by]
+      #
+      # @return [AccessControl]
+      # @raise [ArgumentError] if the resource is not persisted
+      def self.for(resource:, query_service:)
+        Hyrax::Acl::CustomQueries::FindAccessControl.new(query_service: query_service).find_access_control_for(resource: resource)
+      rescue Valkyrie::Persistence::ObjectNotFoundError
+        new(access_to: resource.id, permissions: [])
+      end
+    end
+  end
+end

data/lib/hyrax/acl/access_control_change_set.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module Acl
+    ##
+    # A ChangeSet for Hyrax::Acl::AccessControl.
+    class AccessControlChangeSet < Valkyrie::ChangeSet
+      property :access_to, type: Valkyrie::Types::ID, default: nil
+      property :permissions, type: Valkyrie::Types::Set.of(Hyrax::Acl::Permission), default: nil
+    end
+  end
+end

data/lib/hyrax/acl/access_control_list.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module Acl
+    ##
+    # @api public
+    #
+    # ACLs for `Hyrax::Resource` models
+    #
+    # Allows managing `Hyrax::Permission` entries referring to a specific
+    # `Hyrax::Resource.
+    #
+    class AccessControlList
+      DISCOVER = :discover
+      EDIT     = :edit
+      READ     = :read
+
+      ##
+      # @!attribute [rw] resource
+      #   @return [Valkyrie::Resource]
+      # @!attribute [r] persister
+      #   @return [#save]
+      # @!attribute [r] query_service
+      #   @return [#find_inverse_references_by]
+      attr_reader :persister, :query_service
+      attr_accessor :resource
+
+      ##
+      # @param resource [Valkyrie::Resource]
+      # @param persister [#save] defaults to the configured Hyrax persister
+      # @param query_service [#find_inverse_references_by] defaults to the
+      #   configured Hyrax query service
+      def initialize(resource:, persister:, query_service:)
+        self.resource  = resource
+        @persister     = persister
+        @query_service = query_service
+      end
+
+      ##
+      # @api public
+      #
+      # @param permission [Hyrax::Permission]
+      #
+      # @return [Boolean]
+      def <<(permission)
+        permission.access_to = resource.id
+
+        change_set.permissions += [permission]
+
+        true
+      end
+      alias add <<
+
+      ##
+      # @api public
+      #
+      # @param permission [Hyrax::Permission]
+      #
+      # @return [Boolean]
+      def delete(permission)
+        change_set.permissions -= [permission]
+
+        true
+      end
+
+      ##
+      # @api public
+      #
+      # @example
+      #    user = User.find('user_id')
+      #
+      #    acl.grant(:read).to(user)
+      def grant(mode)
+        ModeGrant.new(self, mode)
+      end
+
+      ##
+      # Discover grant
+      # @agent [Hyrax::Acl::Agent] agent
+      def has_discover?(agent:)
+        has_grant?(mode: DISCOVER, agent: agent)
+      end
+
+      ##
+      # Read grant
+      # @agent [Hyrax::Acl::Agent] agent
+      def has_read?(agent:)
+        has_grant?(mode: READ, agent: agent)
+      end
+
+      ##
+      # Edit grant
+      # @agent [Hyrax::Acl::Agent] agent
+      def has_edit?(agent:)
+        has_grant?(mode: EDIT, agent: agent)
+      end
+
+      ##
+      # Edit grant
+      # @agent [Hyrax::Acl::Agent] agent
+      def has_grant?(mode:, agent:)
+        permissions.any? do |permission|
+          permission.mode ==  mode && permission.agent == agent.agent_key
+        end
+      end
+
+      ##
+      # @api public
+      #
+      # @return [Boolean]
+      def pending_changes?
+        change_set.changed?
+      end
+
+      ##
+      # @api public
+      #
+      # @return [Set<Hyrax::Permission>]
+      def permissions
+        Set.new(change_set.permissions)
+      end
+
+      ##
+      # @api public
+      #
+      # @example
+      #    user = User.find('user_id')
+      #
+      #    acl.revoke(:read).from(user)
+      def revoke(mode)
+        ModeRevoke.new(self, mode)
+      end
+
+      ##
+      # @api public
+      #
+      # Saves the ACL for the resource, by saving each permission policy
+      #
+      # @yield [acl] gives self to the block only if the save is successful
+      # @return [Boolean]
+      def save
+        return true unless pending_changes?
+
+        change_set.sync
+        persister.save(resource: change_set.resource)
+        yield self if block_given?
+        @change_set = nil
+
+        true
+      end
+
+      private
+
+      ##
+      # @api private
+      def access_control_model
+        AccessControl.for(resource: resource, query_service: query_service)
+      end
+
+      ##
+      # @api private
+      def change_set
+        @change_set ||= AccessControlChangeSet.new(access_control_model)
+      end
+
+      ##
+      # @abstract
+      # @api private
+      class ModeEditor
+        def initialize(acl, mode)
+          @acl  = acl
+          @mode = mode.to_sym
+        end
+
+        private
+
+        ##
+        # Returns the identifier used by ACLs to identify agents.
+        #
+        # This defaults to the `:agent_key`, but if that method doesn’t exist,
+        # `:user_key` will be used as a fallback.
+        def id_for(agent:)
+          key = agent.try(:agent_key) || agent.user_key
+          key.to_s
+        end
+      end
+
+      ##
+      # @api private
+      #
+      # A short-term memory object for the permission granting DSL. Use with
+      # method chaining, as in: `acl.grant(:edit).to(user)`.
+      class ModeGrant < ModeEditor
+        ##
+        # @api public
+        # @return [Hyrax::AccessControlList]
+        def to(user_or_group)
+          agent_id = id_for(agent: user_or_group)
+
+          @acl << Hyrax::Acl::Permission.new(access_to: @acl.resource.id, agent: agent_id, mode: @mode)
+          @acl
+        end
+      end
+
+      ##
+      # @api private
+      #
+      # A short-term memory object for the permission revoking DSL. Use with
+      # method chaining, as in: `acl.revoke(:edit).from(user)`.
+      class ModeRevoke < ModeEditor
+        ##
+        # @api public
+        # @return [Hyrax::AccessControlList]
+        def from(user_or_group)
+          permission_for_deletion = @acl.permissions.find do |p|
+            p.mode == @mode &&
+              p.agent.to_s == id_for(agent: user_or_group)
+          end
+
+          @acl.delete(permission_for_deletion) if permission_for_deletion
+          @acl
+        end
+      end
+    end
+  end
+end

data/lib/hyrax/acl/agent.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module Acl
+    class Agent
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      ##
+      # @return [String] a local identifier in ACL
+      #   data
+      def agent_key
+        name
+      end
+    end
+  end
+end

data/lib/hyrax/acl/custom_queries/find_access_control.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+module Hyrax
+  module Acl
+    module CustomQueries
+      # @example
+      #   Hyrax.custom_queries.find_access_control_for(resource: resource)
+      class FindAccessControl
+        def self.queries
+          [:find_access_control_for]
+        end
+
+        def initialize(query_service:)
+          @query_service = query_service
+        end
+
+        attr_reader :query_service
+        delegate :resource_factory, to: :query_service
+
+        def find_access_control_for(resource: )
+          query_service
+            .find_inverse_references_by(resource: resource, property: :access_to)
+            .find { |r| r.is_a?(Hyrax::Acl::AccessControl) } ||
+            raise(Valkyrie::Persistence::ObjectNotFoundError)
+        rescue ArgumentError # some adapters raise ArgumentError for missing resources
+          raise(Valkyrie::Persistence::ObjectNotFoundError)
+        end
+      end
+    end
+  end
+end

data/lib/hyrax/acl/custom_queries.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'hyrax/acl/custom_queries/find_access_control'
+
+module Hyrax
+  module Acl
+    ##
+    # @see https://github.com/samvera/valkyrie/wiki/Queries#custom-queries
+    # @see https://github.com/samvera/hyrax/wiki/Hyrax-Valkyrie-Usage-Guide#custom-queriesy
+    module CustomQueries
+    end
+  end
+end

data/lib/hyrax/acl/group.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Hyrax
+  module Acl
+    class Group < Agent
+      DEFAULT_NAME_PREFIX = 'group/'
+
+      def self.name_prefix
+        DEFAULT_NAME_PREFIX
+      end
+
+      ##
+      # @return [Hyrax::Group]
+      def self.from_agent_key(key)
+        new(key.delete_prefix(name_prefix))
+      end
+
+      def initialize(name)
+        super
+      end
+
+      ##
+      # @return [String] a local identifier for this group; for use (e.g.) in ACL
+      #   data
+      def agent_key
+        self.class.name_prefix + name
+      end
+
+      ##
+      # @return [Boolean]
+      def ==(other)
+        other.class == self.class && other.name == name
+      end
+    end
+  end
+end

data/lib/hyrax/acl/permission.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module Acl
+    ##
+    # Valkyrie native permissions (access policies) for Hyrax
+    #
+    # Permissions are persisted independently from `Hyrax::Resource`s (works,
+    # collections, file sets, etc...) since their scope is different. Access policies
+    # may be application-specific and tend to update more frequently than resource
+    # metadata. This approach also allows policies to be persisted using a
+    # different database or adapter than is used for curatorial objects.
+    class Permission < Valkyrie::Resource
+      include Dry::Equalizer(:access_to, :agent, :mode)
+
+      attribute :access_to, Valkyrie::Types::ID
+      attribute :agent,     Valkyrie::Types::String
+      attribute :mode,      Valkyrie::Types::Coercible::Symbol
+    end
+  end
+end

data/lib/hyrax/acl/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module Hyrax
+  module Acl
+    VERSION = '0.1.0'
+  end
+end

data/lib/hyrax/acl.rb

@@ -0,0 +1,13 @@
+require 'valkyrie'
+require 'hyrax/acl/agent'
+require 'hyrax/acl/group'
+require 'hyrax/acl/permission'
+require 'hyrax/acl/access_control'
+require 'hyrax/acl/custom_queries'
+require 'hyrax/acl/access_control_change_set'
+require 'hyrax/acl/access_control_list'
+
+##
+# Hyrax Access Control Lists
+module Acl
+end

data/lib/hyrax.rb

@@ -0,0 +1,2 @@
+module Hyrax
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: hyrax-acl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Project Surfliner
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-07-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: valkyrie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: Access Control List models and support for Hyrax
+email:
+- tomjohnson@ucsb.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- Gemfile
+- Gemfile.lock
+- README.md
+- hyrax-acl.gemspec
+- lib/hyrax.rb
+- lib/hyrax/acl.rb
+- lib/hyrax/acl/access_control.rb
+- lib/hyrax/acl/access_control_change_set.rb
+- lib/hyrax/acl/access_control_list.rb
+- lib/hyrax/acl/agent.rb
+- lib/hyrax/acl/custom_queries.rb
+- lib/hyrax/acl/custom_queries/find_access_control.rb
+- lib/hyrax/acl/group.rb
+- lib/hyrax/acl/permission.rb
+- lib/hyrax/acl/version.rb
+homepage: http://github.com/samvera-labs/hyrax-acl
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Hyrax Access Control List
+test_files: []