phi_attrs 0.2.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6271ebbfae4a5ddad7aa1ad27b812cc4056a5a4958b1067ddf2aa717975b738
-  data.tar.gz: '098ec65389f50bbe24876657a1ff9eb78bbbe17fb5192804ebbc2f75eedd97f4'
+  metadata.gz: 1cc2ab95144c51b9ce2322864983ff9302d65d3e585c8ced98f1fe3098761173
+  data.tar.gz: 377a9e45f0069b4817a9156a66969b3056553707ae0f6a61716c16cbdc978a8a
 SHA512:
-  metadata.gz: a5832351881d96019071f9b77ac4e08b991104dca6f47c8a1917f5c3546002d7510c5d0fe7ceaa4fe37df7006ec71105acbbcc99a5c9928e57e78b43a7cd2d5d
-  data.tar.gz: 3a153bd1a992dbbb94de889f8a82c22f969dd1bb9b9f36254485d0265f70cba89d89f1c8b424e30056aa1c23c5b8e8be3142d7b5ccfed05c970ec67aa3614d69
+  metadata.gz: 78aa212eceac4e6b0ef10289ac0517b3d9943add98550fcffbc374e9d3d773ab3395d0cfae792161b6793f05fd7a08347e60b76201a6c719954956c902396fb2
+  data.tar.gz: 8fed8925c193caf3c169dff50800766d0abd9b45e6dd652de31b93b8219a2c3d425ac111a9c4b8608fbbfbc23a2e038f13bda2d89004a65fa801eb15dfcdbb37

data/.github/workflows/build.yml

@@ -11,15 +11,14 @@ jobs:
         ruby: [2.5, 2.6, 2.7]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Ruby ${{ matrix.ruby }}
-        uses: actions/setup-ruby@v1
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
       - name: Install dependencies
         run: |
-          gem install bundler
-          bundle install
           bundle exec appraisal install
       - name: Run rspec
         run: bundler exec appraisal rspec

data/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish Gem
+
+on:
+  push:
+    branches:
+      - "main"
+    tags:
+      - v*
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '2.6'
+          bundler-cache: true
+      - name: Release Gem
+        if: contains(github.ref, 'refs/tags/v')
+        uses: cadwallion/publish-rubygems-action@master
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          RUBYGEMS_API_KEY: ${{secrets.RUBYGEMS_API_KEY}}
+          RELEASE_COMMAND: bundle exec rake release

data/README.md

@@ -39,7 +39,7 @@ Or install it yourself as:
 
 ## Initialize
 
-Create an initializer to configure the PHI log file location.
+Create an initializer to configure the PHI log file location. Log rotation can be configured with log_shift_age and log_shift_size (disabled by default).
 
 Example:
 
@@ -48,6 +48,8 @@ Example:
 ```ruby
 PhiAttrs.configure do |conf|
   conf.log_path = Rails.root.join("log", "phi_access_#{Rails.env}.log")
+  conf.log_shift_age  = 10            # how many logs to keep of `log_shift_size` or frequency to rotate ('daily', 'weekly' or 'monthly'). Disable rotation with 0 (default).
+  conf.log_shift_size = 100.megabytes # size in bytes when using `log_shift_age` as a number
 end
 ```
 
@@ -275,7 +277,7 @@ There is also a block syntax of `disallow_phi` for temporary suppression phi acc
 ```ruby
 patient = PatientInfo.find(params[:id])
 patient.allow_phi!('allowed_user@example.com', 'Display Patient Data')
-patient.diallow_phi do
+patient.disallow_phi do
   @data = patient.to_json # PHIAccessException
 end # Access is allowed again beyond this point
 ```
@@ -284,7 +286,7 @@ or a block level on a class:
 
 ```ruby
 PatientInfo.allow_phi!('allowed_user@example.com', 'Display Patient Data')
-PatientInfo.diallow_phi do
+PatientInfo.disallow_phi do
   @data = PatientInfo.find(params[:id]).to_json # PHIAccessException
 end # Access is allowed again beyond this point
 ```
@@ -391,6 +393,27 @@ person_phi.allow_phi(nil, "Because I felt like looking at PHI") do
 end
 ```
 
+### Request UUID
+
+It can be helpful to include the Rails request UUID to match up your general application
+logs to your PHI access logs. The following snippet will prepend your PHI access logs
+with the request UUID.
+
+#### `app/controllers/application_controller.rb`
+
+```ruby
+around_action :tag_phi_log_with_request_id
+
+...
+
+private
+
+def tag_phi_log_with_request_id
+  PhiAttrs::Logger.logger.tagged("Request ID: #{request.uuid}") do
+    yield
+  end
+end
+```
 ## Best Practices
 
 * Mix and matching `instance`, `class` and `block` syntaxes for allowing/denying PHI is not recommended.

data/lib/phi_attrs/configure.rb

@@ -2,6 +2,8 @@
 
 module PhiAttrs
   @@log_path = nil
+  @@log_shift_age = 0 # Default to disabled
+  @@log_shift_size = 1048576 # 1MB - Default from logger class
   @@current_user_method = nil
   @@translation_prefix = 'phi'
 
@@ -17,6 +19,22 @@ module PhiAttrs
     @@log_path = value
   end
 
+  def self.log_shift_age
+    @@log_shift_age
+  end
+
+  def self.log_shift_age=(value)
+    @@log_shift_age = value
+  end
+
+  def self.log_shift_size
+    @@log_shift_size
+  end
+
+  def self.log_shift_size=(value)
+    @@log_shift_size = value
+  end
+
   def self.translation_prefix
     @@translation_prefix
   end

data/lib/phi_attrs/logger.rb

@@ -7,7 +7,7 @@ module PhiAttrs
     class << self
       def logger
         unless @logger
-          logger = ActiveSupport::Logger.new(PhiAttrs.log_path)
+          logger = ActiveSupport::Logger.new(PhiAttrs.log_path, PhiAttrs.log_shift_age, PhiAttrs.log_shift_size)
           logger.formatter = Formatter.new
           @logger = ActiveSupport::TaggedLogging.new(logger)
         end

data/lib/phi_attrs/phi_record.rb

@@ -107,8 +107,32 @@ module PhiAttrs
       #   end
       #   # PHI Access Disallowed
       #
-      def allow_phi(user_id = nil, reason = nil, allow_only: nil)
-        raise ArgumentError, 'block required. use allow_phi! without block' unless block_given?
+      def allow_phi(user_id = nil, reason = nil, allow_only: nil, &block)
+        get_phi(user_id, reason, allow_only: allow_only, &block)
+        return
+      end
+
+
+      # Enable PHI access for any instance of this class in the block given only
+      # returning whatever the block returns.
+      #
+      # @param [String] user_id                       A unique identifier for the person accessing the PHI
+      # @param [String] reason                        The reason for accessing PHI
+      # @param [collection of PhiRecord] allow_only   Specific PhiRecords to allow access to
+      # &block [block]                                The block in which PHI access is allowed for the class
+      #
+      # @example
+      #   results = Foo.allow_phi('user@example.com', 'viewing patient record') do
+      #     Foo.search(params)
+      #   end
+      #
+      # @example
+      #   loaded_foo = Foo.allow_phi('user@example.com', 'exporting patient list', allow_only: list_of_foos) do
+      #     Bar.find_by(foo: list_of_foos).include(:foo)
+      #   end
+      #
+      def get_phi(user_id = nil, reason = nil, allow_only: nil)
+        raise ArgumentError, 'block required' unless block_given?
 
         if allow_only.present?
           raise ArgumentError, 'allow_only must be iterable with each' unless allow_only.respond_to?(:each)
@@ -125,7 +149,7 @@ module PhiAttrs
           allow_only.each { |t| t.allow_phi!(user_id, reason) }
         end
 
-        yield if block_given?
+        result = yield if block_given?
 
         __instances_with_extended_phi.each do |obj|
           if frozen_instances.include?(obj)
@@ -143,6 +167,8 @@ module PhiAttrs
           allow_only.each { |t| t.disallow_last_phi!(preserve_extensions: true) }
           # We've handled any newly extended allowances ourselves above
         end
+
+        result
       end
 
       # Explicitly disallow phi access in a specific area of code. This does not
@@ -335,17 +361,41 @@ module PhiAttrs
     #   end
     #   # PHI Access Disallowed Here
     #
-    def allow_phi(user_id = nil, reason = nil)
-      raise ArgumentError, 'block required. use allow_phi! without block' unless block_given?
+    def allow_phi(user_id = nil, reason = nil, &block)
+      get_phi(user_id, reason, &block)
+      return
+    end
+
+
+    # Enable PHI access for a single instance of this class inside the block.
+    # Returns whatever is returned from the block.
+    # Nested calls to get_phi will log once per nested call
+    #s
+    # @param [String] user_id   A unique identifier for the person accessing the PHI
+    # @param [String] reason    The reason for accessing PHI
+    # @yield                    The block in which phi access is allowed
+    #
+    # @return PHI
+    #
+    # @example
+    #   foo = Foo.find(1)
+    #   phi_data = foo.get_phi('user@example.com', 'viewing patient record') do
+    #    foo.phi_field
+    #   end
+    #
+    def get_phi(user_id = nil, reason = nil)
+      raise ArgumentError, 'block required' unless block_given?
 
       extended_instances = @__phi_relations_extended.clone
       allow_phi!(user_id, reason)
 
-      yield if block_given?
+      result = yield if block_given?
 
       new_extensions = @__phi_relations_extended - extended_instances
       disallow_last_phi!(preserve_extensions: true)
       revoke_extended_phi!(new_extensions) if new_extensions.any?
+
+      result
     end
 
     # Revoke all PHI access for a single instance of this class.
@@ -412,6 +462,25 @@ module PhiAttrs
       end
     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.
+    #
+    # @return [String] the user_id passed in to allow_phi!
+    #
+    def phi_allowed_by
+      phi_context[:user_id]
+    end
+
+    # The access reason for allowing access to this instance.
+    # This is what was passed in when PhiRecord#allow_phi! was called.
+    #
+    # @return [String] the reason passed in to allow_phi!
+    #
+    def phi_access_reason
+      phi_context[:reason]
+    end
+
     # Whether PHI access is allowed for a single instance of this class
     #
     # @example
@@ -424,6 +493,18 @@ module PhiAttrs
       !phi_context.nil? && phi_context[:phi_access_allowed]
     end
 
+    # Require phi access. Raises an error pre-emptively if it has not been granted.
+    #
+    # @example
+    #   def use_phi(patient_record)
+    #     patient_record.require_phi!
+    #     # ...use PHI Freely
+    #   end
+    #
+    def require_phi!
+      raise PhiAccessException, 'PHI Access required, please call allow_phi or allow_phi! first' unless phi_allowed?
+    end
+
     def reload
       @__phi_relations_extended.clear
       super
@@ -479,28 +560,6 @@ module PhiAttrs
       @__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_context[: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_context[:reason]
-    end
-
     def phi_context
       instance_phi_context || class_phi_context
     end

data/lib/phi_attrs/rspec.rb

@@ -0,0 +1,43 @@
+require 'rspec/expectations'
+
+DO_NOT_SPECIFY = "do not specify `allowed_by` or `with_access_reason` for negated `allow_phi_access`"
+
+RSpec::Matchers.define :allow_phi_access do
+  match do |result|
+    @allowed = result.phi_allowed?
+    @user_id_matches = @user_id.nil? || @user_id == result.phi_allowed_by
+    @reason_matches = @reason.nil? || @reason == result.phi_access_reason
+
+    @allowed && @user_id_matches && @reason_matches
+  end
+
+  match_when_negated do |result|
+    raise ArgumentError, DO_NOT_SPECIFY unless @user_id.nil? && @reason.nil?
+
+    !result.phi_allowed?
+  end
+
+  chain :allowed_by do |user_id|
+    @user_id = user_id
+  end
+
+  chain :with_access_reason do |reason|
+    @reason = reason
+  end
+
+  # :nocov:
+  failure_message do |result|
+    msgs = []
+
+    msgs = ['PHI Access was not allowed.'] unless @allowed
+    msgs << "PHI Access was allowed by '#{result.phi_allowed_by}' (not '#{@user_id}')." unless @user_id_matches
+    msgs << "PHI Access was allowed because '#{result.phi_access_reason}' (not because '#{@reason}')." unless @reason_matches
+
+    msgs.join "\n"
+  end
+
+  failure_message_when_negated do |result|
+    "PHI access was allowed by '#{result.phi_allowed_by}', because '#{result.phi_access_reason}'"
+  end
+  # :nocov:
+end

data/lib/phi_attrs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PhiAttrs
-  VERSION = '0.2.1'
+  VERSION = '0.2.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phi_attrs
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.4
 platform: ruby
 authors:
 - Wyatt Kirby
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-11-10 00:00:00.000000000 Z
+date: 2022-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -228,6 +228,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/build.yml"
+- ".github/workflows/publish.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -259,6 +260,7 @@ files:
 - lib/phi_attrs/logger.rb
 - lib/phi_attrs/phi_record.rb
 - lib/phi_attrs/railtie.rb
+- lib/phi_attrs/rspec.rb
 - lib/phi_attrs/version.rb
 - phi_attrs.gemspec
 homepage: http://www.apsis.io
@@ -283,7 +285,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.3.26
 signing_key: 
 specification_version: 4
 summary: PHI Access Restriction & Logging for Rails ActiveRecord