phi_attrs 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 07c9497b2d8b7c17ad211cd9bd9ed40fdf669e78
-  data.tar.gz: 3e42b4499d9b45d1f46a52d325869f171becb27d
+  metadata.gz: 3eacb70390f2672da6d28043638c4c50e54c5097
+  data.tar.gz: cc5f1b55c52300d1588d168f94168cef75219590
 SHA512:
-  metadata.gz: 7f4e4acdcc682ba9b0cca43644f39a248ea3878e2138d8c6105246c74d9df6c1ad1c304cec13a790398c7430b70b140f56d60e701e973c374a9dfc250ef65a3c
-  data.tar.gz: 67737de996af40fa8ceea1b68a69f2ce516e7035c02d0e70183e8b56058e2a17ea2e6d5fb2030cf9df25a0e688072e1cc871c0b41ae365544f50132cf6a26bd0
+  metadata.gz: 0a3405b39cbe9006b92184db10ad4e31698512a5c742f43a201724042968e216ecde4977371f63d898a3143ca13e5bfcbbfe9cf7b47a53018d2103703d3ec1a4
+  data.tar.gz: b32c79d5304fe6c8bcecc94939b62b1d0d97cbae17db0aa3bc75dc5b47da01bd450f31e8a35113d18ec2542d4f047ca4e6e3aa73ad745b7f82f01450e92860b2

data/README.md

@@ -1,5 +1,7 @@
 # PhiAttrs
 
+[![Gem Version](https://badge.fury.io/rb/phi_attrs.svg)](https://badge.fury.io/rb/phi_attrs) [![Build Status](https://travis-ci.org/apsislabs/phi_attrs.svg?branch=master)](https://travis-ci.org/apsislabs/phi_attrs)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -32,16 +34,42 @@ end
 ```
 
 Access is granted on a model level:
+
 ```ruby
 info = new PatientInfo
 info.allow_phi!("allowed_user@example.com", "Customer Service")
 ```
 
 or a class:
+
 ```ruby
 PatientInfo.allow_phi!("allowed_user@example.com", "Customer Service")
 ```
 
+### Extending PHI Access
+
+Sometimes you'll have a single mental model that is composed of several `ActiveRecord` models joined by association. In this case, instead of calling `allow_phi!` on all joined models, we expose a shorthand of extending PHI access to related models.
+
+```ruby
+class PatientInfo < ActiveRecord::Base
+  phi_model
+end
+
+class Patient < ActiveRecord::Base
+  has_one :patient_info
+
+  phi_model
+
+  extend_phi_access :patient_info
+end
+
+patient = Patient.new
+patient.allow_phi!('user@example.com', 'reason')
+patient.patient_info.first_name
+```
+
+**NOTE:** This is not intended to be used on all relationships! Only those where you intend to grant implicit access based on access to another model. In this use case, we assume that allowed access to `Patient` implies allowed access to `PatientInfo`, and therefore does not require an additional `allow_phi!` check.
+
 ## 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.
@@ -50,8 +78,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ### Docker
 
-* `docker-compose up`
-* `bin/ssh_to_container`
+-   `docker-compose up`
+-   `bin/ssh_to_container`
 
 ## Testing
 

data/lib/phi_attrs/phi_record.rb

@@ -1,6 +1,12 @@
+# Namespace for classes and modules that handle PHI Attribute Access Logging
 module PhiAttrs
   PHI_ACCESS_LOG_TAG = 'PHI Access Log'.freeze
 
+  # Module for extending ActiveRecord models to handle PHI access logging
+  # and restrict access to attributes.
+  #
+  # @author Apsis Labs
+  # @since 0.1.0
   module PhiRecord
     extend ActiveSupport::Concern
 
@@ -17,18 +23,51 @@ module PhiAttrs
     end
 
     class_methods do
+      # Set methods to be excluded from PHI access logging.
+      #
+      # @param [Array<Symbol>] *methods Any number of methods to exclude
+      #
+      # @example
+      #   exclude_from_phi :foo, :bar
+      #
       def exclude_from_phi(*methods)
         self.__phi_exclude_methods = methods.map(&:to_s)
       end
 
+      # Set methods to be explicitly included in PHI access logging.
+      #
+      # @param [Array<Symbol>] *methods Any number of methods to include
+      #
+      # @example
+      #   include_in_phi :foo, :bar
+      #
       def include_in_phi(*methods)
         self.__phi_include_methods = methods.map(&:to_s)
       end
 
+      # Set of methods which should be implicitly allowed if this object
+      # is allowed. The methods that are extended should return ActiveRecord
+      # models that also extend PhiAttrs.
+      #
+      # If they do not, this is essentially an alias for PhiRecord#include_in_phi
+      #
+      # @param [Array<Symbol>] *methods Any number of methods to extend access to
+      #
+      # @example
+      #   extend_phi_access :foo, :bar
+      #
       def extend_phi_access(*methods)
         self.__phi_extended_methods = methods.map(&:to_s)
       end
 
+      # Enable PHI access for any instance of this class.
+      #
+      # @param [String] user_id   A unique identifier for the person accessing the PHI
+      # @param [String] reason    The reason for accessing PHI
+      #
+      # @example
+      #   Foo.allow_phi!('user@example.com', 'viewing patient record')
+      #
       def allow_phi!(user_id, reason)
         RequestStore.store[:phi_access] ||= {}
 
@@ -37,11 +76,17 @@ module PhiAttrs
           user_id: user_id,
           reason: reason
         }
+
         PhiAttrs::Logger.tagged(PHI_ACCESS_LOG_TAG, name) do
           PhiAttrs::Logger.info("PHI Access Enabled for #{user_id}: #{reason}")
         end
       end
 
+      # Revoke PHI access for this class, if enabled by PhiRecord#allow_phi!
+      #
+      # @example
+      #   Foo.disallow_phi!
+      #
       def disallow_phi!
         RequestStore.store[:phi_access].delete(name) if RequestStore.store[:phi_access].present?
         PhiAttrs::Logger.tagged(PHI_ACCESS_LOG_TAG, name) do
@@ -50,22 +95,27 @@ module PhiAttrs
       end
     end
 
-    def wrap_phi
-      # Disable PHI access by default
-      @__phi_access_allowed = false
-      @__phi_access_logged = false
-
-      # Wrap attributes with PHI Logger and Access Control
-      __phi_wrapped_methods.each { |attr| phi_wrap_method(attr) }
-    end
-
+    # Get all method names to be wrapped with PHI access logging
+    #
+    # @return [Array<String>] the method names to be wrapped with PHI access logging
+    #
     def __phi_wrapped_methods
-      associations = self.class.reflect_on_all_associations.map(&:name).map(&:to_s)
+      extended_methods = self.class.__phi_extended_methods.to_a
       excluded_methods = self.class.__phi_exclude_methods.to_a
       included_methods = self.class.__phi_include_methods.to_a
-      associations + attribute_names - excluded_methods + included_methods - [self.class.primary_key]
+
+      extended_methods + attribute_names - excluded_methods + included_methods - [self.class.primary_key]
     end
 
+    # Enable PHI access for a single instance of this class.
+    #
+    # @param [String] user_id   A unique identifier for the person accessing the PHI
+    # @param [String] reason    The reason for accessing PHI
+    #
+    # @example
+    #   foo = Foo.find(1)
+    #   foo.allow_phi!('user@example.com', 'viewing patient record')
+    #
     def allow_phi!(user_id, reason)
       PhiAttrs::Logger.tagged(*phi_log_keys) do
         @__phi_access_allowed = true
@@ -76,6 +126,12 @@ module PhiAttrs
       end
     end
 
+    # Revoke PHI access for a single instance of this class
+    #
+    # @example
+    #   foo = Foo.find(1)
+    #   foo.disallow_phi!
+    #
     def disallow_phi!
       PhiAttrs::Logger.tagged(*phi_log_keys) do
         @__phi_access_allowed = false
@@ -86,25 +142,104 @@ module PhiAttrs
       end
     end
 
+    # Whether PHI access is allowed for a single instance of this class
+    #
+    # @example
+    #   foo = Foo.find(1)
+    #   foo.phi_allowed?
+    #
+    # @return [Boolean] whether PHI access is allowed for this instance
+    #
     def phi_allowed?
       @__phi_access_allowed || RequestStore.store.dig(:phi_access, self.class.name, :phi_access_allowed)
     end
 
-    def phi_allowed_by
-      @__phi_user_id || RequestStore.store.dig(:phi_access, self.class.name, :user_id)
-    end
+    private
 
-    def phi_access_reason
-      @__phi_access_reason || RequestStore.store.dig(:phi_access, self.class.name, :reason)
-    end
+    # Entry point for wrapping methods with PHI access logging. This is called
+    # by an `after_initialize` hook from ActiveRecord.
+    #
+    # @private
+    #
+    def wrap_phi
+      # Disable PHI access by default
+      @__phi_access_allowed = false
+      @__phi_access_logged = false
 
-    private
+      # Wrap attributes with PHI Logger and Access Control
+      __phi_wrapped_methods.each { |attr| phi_wrap_method(attr) }
+    end
 
+    # Log Key for an instance of this class. If the instance is persisted in the
+    # database, then it is the primary key; otherwise it is the Ruby object_id
+    # in memory.
+    #
+    # This is used by the tagged logger for tagging all log entries to find
+    # the underlying model.
+    #
+    # @private
+    #
+    # @return [Array<String>] log key for an instance of this class
+    #
     def phi_log_keys
       @__phi_log_id = persisted? ? "Key: #{attributes[self.class.primary_key]}" : "Object: #{object_id}"
       @__phi_log_keys = [PHI_ACCESS_LOG_TAG, self.class.name, @__phi_log_id]
     end
 
+    # The unique identifier for whom access has been allowed on this instance.
+    # This is what was passed in when PhiRecord#allow_phi! was called.
+    #
+    # @private
+    #
+    # @return [String] the user_id passed in to allow_phi!
+    #
+    def phi_allowed_by
+      @__phi_user_id || RequestStore.store.dig(:phi_access, self.class.name, :user_id)
+    end
+
+    # The access reason for allowing access to this instance.
+    # This is what was passed in when PhiRecord#allow_phi! was called.
+    #
+    # @private
+    #
+    # @return [String] the reason passed in to allow_phi!
+    #
+    def phi_access_reason
+      @__phi_access_reason || RequestStore.store.dig(:phi_access, self.class.name, :reason)
+    end
+
+    # Core logic for wrapping methods in PHI access logging and access restriction.
+    #
+    # This method takes a single method name, and creates a new method using
+    # define_method; once this method is defined, the original method name
+    # is aliased to the new method, and the original method is renamed to a
+    # known key.
+    #
+    # @private
+    #
+    # @example
+    #   Foo::phi_wrap_method(:bar)
+    #
+    #   foo = Foo.find(1)
+    #   foo.bar # => raises PHI Access Exception
+    #
+    #   foo.allow_phi!('user@example.com', 'testing')
+    #
+    #   foo.bar # => returns original value of Foo#bar
+    #
+    #   # defines two new methods:
+    #   #   __bar_phi_wrapped
+    #   #   __bar_phi_unwrapped
+    #   #
+    #   # After these methods are defined
+    #   # an alias chain is created that
+    #   # roughly maps:
+    #   #
+    #   # bar => __bar_phi_wrapped => __bar_phi_unwrapped
+    #   #
+    #   # This ensures that all calls to Foo#bar pass
+    #   # through access logging.
+    #
     def phi_wrap_method(method_name)
       return if self.class.__phi_methods_wrapped.include? method_name
 

data/lib/phi_attrs/version.rb

@@ -1,3 +1,3 @@
 module PhiAttrs
-  VERSION = '0.1.2'.freeze
+  VERSION = '0.1.3'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phi_attrs
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Wyatt Kirby