anony 1.0.0

data/anony.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "anony/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "anony"
+  spec.version       = Anony::VERSION
+  spec.authors       = ["GoCardless Engineering"]
+  spec.email         = ["engineering@gocardless.com"]
+
+  spec.summary       = "A small library that defines how ActiveRecord models should be " \
+                       "anonymised for deletion purposes."
+  spec.homepage      = "https://github.com/gocardless/anony"
+  spec.license       = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.4"
+
+  spec.add_development_dependency "bundler", "~> 2.1.4"
+  spec.add_development_dependency "gc_ruboconfig", "~> 2.9.0"
+  spec.add_development_dependency "rspec", "~> 3.9"
+  spec.add_development_dependency "rspec_junit_formatter", "~> 0.4"
+  spec.add_development_dependency "yard", "~> 0.9.20"
+
+  # For integration testing
+  spec.add_development_dependency "sqlite3", "~> 1.4.1"
+
+  spec.add_dependency "activerecord", ">= 5.2", "< 6.1"
+  spec.add_dependency "activesupport", ">= 5.2", "< 6.1"
+end

data/docs/COMPATIBILITY.md

@@ -0,0 +1,17 @@
+# Compatibility
+
+Our goal as Anony maintainers is for the library to be compatible with all supported versions of Ruby and Rails.
+
+Specifically, any CRuby/MRI version that has not received an End of Life notice ([e.g. this notice for Ruby 2.1](https://www.ruby-lang.org/en/news/2017/04/01/support-of-ruby-2-1-has-ended/)) is supported. Similarly, any version of Rails listed as currently supported on [this page](http://guides.rubyonrails.org/maintenance_policy.html) is one we aim to support in Anony.
+
+To that end, [our build matrix](../.circleci/config.yml) includes all these versions.
+
+Any time Anony doesn't work on a supported combination of Ruby and Rails, it's a bug, and can be reported [here](https://github.com/gocardless/Anony/issues).
+
+# Deprecation
+
+Whenever a version of Ruby or Rails falls out of support, we will mirror that change in Anony by updating the build matrix and releasing a new major version.
+
+At that point, we will close any issues that only affect the unsupported version, and may choose to remove any workarounds from the code that are only necessary for the unsupported version.
+
+We will then bump the major version of Anony, to indicate the break in compatibility. Even if the new version of Anony happens to work on the unsupported version of Ruby or Rails, we consider compatibility to be broken at this point.

data/lib/anony.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Anony
+  require_relative "anony/anonymisable"
+  require_relative "anony/config"
+  require_relative "anony/duplicate_strategy_exception"
+  require_relative "anony/field_exception"
+  require_relative "anony/field_level_strategies"
+  require_relative "anony/model_config"
+  require_relative "anony/skipped_exception"
+  require_relative "anony/result"
+end

data/lib/anony/anonymisable.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+require_relative "./strategies/overwrite"
+require_relative "model_config"
+
+module Anony
+  # The main Anony object to include in your ActiveRecord class.
+  #
+  # @example Using in a single model
+  #   class Manager < ApplicationRecord
+  #     include Anony::Anonymisable
+  #   end
+  #
+  # @example Making this available to your whole application
+  #   class ApplicationRecord < ActiveRecord::Base
+  #     include Anony::Anonymisable
+  #   end
+  module Anonymisable
+    # Mixin containing methods that will be exposed on the ActiveRecord class after
+    # including the Anonymisable module.
+    #
+    # The primary method, .anonymise, is used to configure the strategies to apply. This
+    # configuration is lazily executed when trying to actually anonymise an instance:
+    # this is because the database or other lazily-loaded properties are not necessarily
+    # available when the class is configured.
+    module ClassMethods
+      # Define a set of anonymisation configuration on the ActiveRecord class.
+      #
+      # @yield A configuration block
+      # @see DSL Anony::Strategies::Overwrite - the methods available inside this block
+      # @example
+      #   class Manager < ApplicationRecord
+      #     anonymise do
+      #       overwrite do
+      #         with_strategy(:first_name) { "ANONYMISED" }
+      #       end
+      #     end
+      #   end
+      def anonymise(&block)
+        @anonymise_config = ModelConfig.new(self, &block)
+      end
+
+      # Check whether the model has been configured correctly. Returns a simple
+      # `true`/`false`. If configuration has not yet been configured, it returns `false`.
+      #
+      # @return [Boolean]
+      # @example
+      #   Manager.valid_anonymisation?
+      def valid_anonymisation?
+        return false unless @anonymise_config
+
+        @anonymise_config.valid?
+      end
+
+      attr_reader :anonymise_config
+    end
+
+    # Run all anonymisation strategies on the model instance before saving it.
+    #
+    # @return [Anony::Result] described if the save was successful, and the fields or errors created
+    # @example
+    #   manager = Manager.first
+    #   manager.anonymise!
+    def anonymise!
+      raise ArgumentError, ".anonymise not yet invoked" unless self.class.anonymise_config
+
+      self.class.anonymise_config.validate!
+      self.class.anonymise_config.apply(self)
+    rescue ActiveRecord::RecordNotSaved, ActiveRecord::RecordNotDestroyed => e
+      Result.failed(e)
+    end
+
+    # @!visibility private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/anony/config.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/attribute_accessors"
+
+module Anony
+  # Configuration which modifies how the gem will behave in your application. It's
+  # recommended practice to configure this in an initializer.
+  #
+  # @example
+  #   # config/initializers/anony.rb
+  #   require "anony"
+  #
+  #   Anony::Config.ignore_fields(:id)
+  module Config
+    mattr_accessor :ignores
+
+    # @!visibility private
+    def self.ignore?(field)
+      # In this case, we want to support literal matches, regular expressions and blocks,
+      # all of which are helpfully handled by Object#===.
+      #
+      # rubocop:disable Style/CaseEquality
+      ignores.any? { |rule| rule === field }
+      # rubocop:enable Style/CaseEquality
+    end
+
+    # A list of database or model properties to be ignored when anonymising. This is
+    # helpful in Rails applications when there are common columns such as `id`,
+    # `created_at` and `updated_at`, which we would never want to try and anonymise.
+    #
+    # By default, this is an empty collection (i.e. no fields are ignored).
+    #
+    # @param [Array<Symbol>] fields A list of fields names to ignore.
+    # @example Ignoring common Rails fields
+    #   Anony::Config.ignore_fields(:id, :created_at, :updated_at)
+    def self.ignore_fields(*fields)
+      self.ignores = Array(fields)
+    end
+
+    self.ignores = []
+  end
+end

data/lib/anony/cops.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "cops/define_deletion_strategy"

data/lib/anony/cops/define_deletion_strategy.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "../version.rb"
+
+module RuboCop
+  module Cop
+    module Lint
+      # This cop checks whether an ActiveRecord model implements the `.anonymise`
+      # preference (using the Anony gem).
+      #
+      # @example Good
+      #   class User < ApplicationRecord
+      #     anonymise do
+      #       overwrite do
+      #         email :email
+      #         hex :given_name
+      #       end
+      #     end
+      #   end
+      #
+      # @example Bad
+      #   class MyNewThing < ApplicationRecord; end
+      class DefineDeletionStrategy < Cop
+        MSG = "Define .anonymise for %<model>s, see https://github.com/gocardless/" \
+              "anony/blob/#{Anony::VERSION}/README.md for details"
+
+        def_node_search :uses_anonymise?, "(send nil? :anonymise)"
+
+        def on_class(node)
+          return unless model?(node)
+          return if uses_anonymise?(node)
+
+          add_offense(node, message: sprintf(MSG, model: class_name(node)))
+        end
+
+        def model?(node)
+          return unless (superclass = node.children[1])
+
+          superclass.const_name == model_superclass_name
+        end
+
+        def class_name(node)
+          node.children[0].const_name
+        end
+
+        def model_superclass_name
+          cop_config["ModelSuperclass"] || "ApplicationRecord"
+        end
+      end
+    end
+  end
+end

data/lib/anony/duplicate_strategy_exception.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Anony
+  # This exception is thrown if you define more than one strategy for the same field.
+  #
+  # @example
+  #   anonymise do
+  #     overwrite do
+  #       ignore :first_name
+  #       nilable :first_name
+  #     end
+  #   end
+  class DuplicateStrategyException < StandardError
+    def initialize(fields)
+      fields = Array(fields)
+      super("Duplicate anonymisation strategy for field(s) #{fields}")
+    end
+  end
+end

data/lib/anony/field_exception.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Anony
+  # This exception is thrown when validating the anonymisation strategies for all fields.
+  # If some are missing, they will be included in the message.
+  #
+  # @example Missing the first_name field
+  #   class Employee
+  #     anonymise { fields { ignore :last_name } }
+  #   end
+  #
+  #   Employee.first.valid_anonymisation?
+  #   => FieldException, Invalid anonymisation strategy for field(s) [:first_name]
+  class FieldException < StandardError
+    def initialize(fields)
+      fields = Array(fields)
+      super("Invalid anonymisation strategy for field(s) #{fields}")
+    end
+  end
+end

data/lib/anony/field_level_strategies.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Anony
+  # This class is a singleton, containing all of the known strategies that Anony can use
+  # to anonymise individual fields in your models.
+  module FieldLevelStrategies
+    # Registers a new Anony strategy (or overwrites an existing strategy) of a given name.
+    # Strategies are then available everywhere inside the `anonymise` block.
+    #
+    # @param name [Symbol] The name of the strategy you'd like to use
+    # @param klass_or_constant [Object] The object you'd like to statically return, or an
+    #   object which responds to `#call(original_value)`.
+    # @yield [original_value] The previous value of the field. The result of the block
+    #   will be applied to that field. If a block is not given, klass_or_constant will be
+    #   used as the strategy instead.
+    # @raise [ArgumentError] If using neither a block nor strategy class
+    #
+    # @example Reversing a string using a block
+    #   Anony::FieldLevelStrategies.register(:reverse) do |original_value|
+    #     original_value.reverse
+    #   end
+    #
+    #   class Manager
+    #     anonymise { reverse :first_name }
+    #   end
+    #
+    # @example Using a named strategy class
+    #   class Classifier
+    #     def self.call(original_value)
+    #       "Classy version of #{original_value}"
+    #     end
+    #   end
+    #
+    #   Anony::FieldLevelStrategies.register(:classify, Classifier)
+    #
+    #   class Manager
+    #     anonymise { classify :resource_type }
+    #   end
+    #
+    # @example Using a constant value
+    #   Anony::FieldLevelStrategies.register(:forty_two, 42)
+    #
+    #   class Manager
+    #     anonymise { forty_two :date_of_birth }
+    #   end
+    def self.register(name, klass_or_constant = nil, &block)
+      if block_given?
+        strategy = block
+      elsif !klass_or_constant.nil?
+        strategy = klass_or_constant
+      else
+        raise ArgumentError, "Must pass either a block, constant value or strategy class"
+      end
+
+      define_method(name) { |*fields| with_strategy(strategy, *fields) }
+
+      @strategies[name] = strategy
+    end
+
+    # Helper method for retrieving the strategy block (or testing that it exists).
+    #
+    # @param name [Symbol] The name of the strategy to retrieve.
+    # @raise [ArgumentError] If the strategy is not already registered
+    def self.[](name)
+      @strategies.fetch(name) do
+        raise ArgumentError, "Unrecognised strategy `#{name.inspect}`"
+      end
+    end
+
+    @strategies = {}
+
+    # @!method email(field)
+    #   Overwrite a field with a randomised email, where the user part is generated with
+    #   `SecureRandom.uuid` and the domain is "example.com".
+    #
+    #   For example, this might generate an email like:
+    #   `"86b5b19d-2224-4c3d-bead-e9d4a1934303@example.com"`
+    #
+    #   @example Overwriting the field called :email_address
+    #     email :email_address
+    register(:email) do
+      sprintf("%<random>s@example.com", random: SecureRandom.uuid)
+    end
+
+    # @!method phone_number(field)
+    #   Overwrite a field with a static phone number. Currently this is "+1 617 555 1294"
+    #   but you would probably want to override this for your use case.
+    #
+    #   @example Overwriting the field called :phone
+    #     phone_number :phone
+    #
+    #   @example Using a different phone number
+    #     Anony::FieldLevelStrategies.register(:phone_number, "+44 07700 000 000")
+    register(:phone_number, "+1 617 555 1294")
+
+    # @!method current_datetime(field)
+    #   Overwrite a field with the current datetime. This is provided by
+    #   `current_time_from_proper_timezone`, an internal method exposed from
+    #   ActiveRecord::Timestamp.
+    #
+    #   @example Overwriting the field called :signed_up_at
+    #     current_datetime :signed_up_at
+    register(:current_datetime) { |_original| current_time_from_proper_timezone }
+
+    # @!method nilable(field)
+    #   Overwrite a field with the value `nil`.
+    #
+    #   @example Overwriting the field called :optional_field
+    #     nilable :optional_field
+    register(:nilable) { nil }
+
+    # @!method noop(field)
+    #   This strategy applies no transformation rules at all. It is used internally by the
+    #   ignore strategy so you should probably use that instead.
+    #
+    #   @see Anony::Strategies::Fields#ignore
+    register(:no_op) { |value| value }
+  end
+end
+
+module Anony
+  module Strategies
+    # This class curries the max_length into itself so it exists as a parameterless block
+    # that can be called by Anony.
+    #
+    # @example Direct usage:
+    #   anonymise do
+    #     overwrite do
+    #       with_strategy(OverwriteHex.new(20), :field, :field)
+    #     end
+    #   end
+    #
+    # @example Helper method, assumes length = 36
+    #   anonymise do
+    #     overwrite do
+    #       hex :field
+    #     end
+    #   end
+    #
+    # @example Helper method with explicit length
+    #   anonymise do
+    #     overwrite do
+    #       hex :field, max_length: 20
+    #     end
+    #   end
+    OverwriteHex = Struct.new(:max_length) do
+      def call(_existing_value)
+        hex_length = max_length / 2 + 1
+        SecureRandom.hex(hex_length)[0, max_length]
+      end
+    end
+  end
+end