anony 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eee3daa49f033d44737b37aee49c2281430cc23a4ea770c4c0891684ed47fbf8
+  data.tar.gz: 2304bfd91b8f503e7c562db4bed2994da418e78180ed11f629630c4122142982
+SHA512:
+  metadata.gz: 7fca58237bbd4a8e22217ac9547475f4f13483532a05ac6fe1a02a3e93bd047f965734b0eca08fb5690fde36ac7b3d1b94129bcffa822c31ed5fc78b93be04ea
+  data.tar.gz: 2eed4ea29fe1c960bff89b2fa41e63a8338c69069d1dea353a675f4a2e6b1e6e8cb62d4a1be7c7b4d8a445b933870eb24f3dfae920bfbef83b5a9daeccc3a640

data/.circleci/config.yml

@@ -0,0 +1,86 @@
+version: 2
+
+references:
+  steps: &steps
+    - checkout
+
+    - type: cache-restore
+      key: anony-bundler-{{ checksum "anony.gemspec" }}
+
+    - run: gem install bundler -v 2.1.4
+    - run: bundle config set path 'vendor/bundle'
+    - run: bundle install
+
+    - type: cache-save
+      key: anony-bundler-{{ checksum "anony.gemspec" }}
+      paths:
+        - vendor/bundle
+
+    - type: shell
+      command: |
+        bundle exec rspec --profile 10 \
+                          --format RspecJunitFormatter \
+                          --out /tmp/test-results/rspec.xml \
+                          --format progress \
+                          spec
+
+    - type: store_test_results
+      path: /tmp/test-results
+
+    - run: bundle exec rubocop --parallel --extra-details --display-style-guide
+
+jobs:
+  ruby24-rails52:
+    docker:
+      - image: ruby:2.4
+        environment:
+          - RAILS_VERSION=5.2
+    steps: *steps
+  ruby25-rails52:
+    docker:
+      - image: ruby:2.5
+        environment:
+          - RAILS_VERSION=5.2
+    steps: *steps
+  ruby25-rails60:
+    docker:
+      - image: ruby:2.5
+        environment:
+          - RAILS_VERSION=6.0
+    steps: *steps
+  ruby26-rails52:
+    docker:
+      - image: ruby:2.6
+        environment:
+          - RAILS_VERSION=5.2
+    steps: *steps
+  ruby26-rails60:
+    docker:
+      - image: ruby:2.6
+        environment:
+          - RAILS_VERSION=6.0
+    steps: *steps
+  ruby27-rails52:
+    docker:
+      - image: ruby:2.7
+        environment:
+          - RAILS_VERSION=5.2
+    steps: *steps
+  ruby27-rails60:
+    docker:
+      - image: ruby:2.7
+        environment:
+          - RAILS_VERSION=6.0
+    steps: *steps
+
+workflows:
+  version: 2
+  tests:
+    jobs:
+      - ruby24-rails52
+      - ruby25-rails52
+      - ruby25-rails60
+      - ruby26-rails52
+      - ruby26-rails60
+      - ruby27-rails52
+      - ruby27-rails60

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Libraries shouldn't check in Gemfile.lock
+Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,9 @@
+inherit_from: .rubocop_todo.yml
+inherit_gem:
+  gc_ruboconfig: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 2.4
+
+Layout/LineLength:
+  Max: 100

data/.rubocop_todo.yml

@@ -0,0 +1,28 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2019-11-11 12:18:14 +0000 using RuboCop version 0.76.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+RSpec/LeakyConstantDeclaration:
+  Exclude:
+    - 'spec/anony/anonymisable_spec.rb'
+    - 'spec/anony/strategies/overwrite_spec.rb'
+
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/anony/anonymisable_spec.rb'
+
+RSpec/NestedGroups:
+  Exclude:
+    - 'spec/anony/anonymisable_spec.rb'
+
+RSpec/FilePath:
+  Exclude:
+    - 'spec/anony/cops/define_deletion_strategy_spec.rb'
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/anony/rspec_shared_examples_spec.rb'

data/.ruby-version

@@ -0,0 +1 @@
+2.6.5

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+# v1.0.0
+
+* Create a result object when calling `anonymise!` [#44](https://github.com/gocardless/anony/pull/44)
+
+# v0.8.0
+
+* Improve the documentation [#45](https://github.com/gocardless/anony/pull/45)
+* Rename fields strategy to overwrite [#46](https://github.com/gocardless/anony/pull/46)
+
+# v0.7.3
+
+* Allow customising the model superclass for the `DefineDeletionStrategy` cop [#36](https://github.com/gocardless/anony/pull/36)
+
+# v0.7.2
+
+* Add ability to prevent anonymisation with `skip_if` [#25](https://github.com/gocardless/anony/pull/25)
+
+# v0.7.1
+
+* Fix breakage when applying a strategy multiple times [#35](https://github.com/gocardless/anony/pull/35)
+
+# v0.7.0
+
+* **BREAKING** Switch to nesting field-level configuration in a `fields` block
+  [#32](https://github.com/gocardless/anony/pull/32). This should just be a case of
+  switching `anonymise { ... }` to `anonymise { fields { ... } }` in most cases, but for
+  more details please check the README.
+* **BREAKING** `Anony::Strategies.register` was renamed to `Anony::FieldLevelStrategies.register`.
+
+# v0.6.0
+
+* Use ActiveRecord::Persistence#current_time_from_proper_timezone [#34](https://github.com/gocardless/anony/pull/34)
+
+# v0.5.0
+
+* Make `valid_anonymisation?` a class method [#24](https://github.com/gocardless/anony/pull/24)
+* Allow dynamic registration of Anony::Strategies [#23](https://github.com/gocardless/anony/pull/23)
+* Only apply anonymisation strategies to columns that are defined [#28](https://github.com/gocardless/anony/pull/28)
+
+# v0.4.0
+
+* Allow using a constant value as a strategy [#19](https://github.com/gocardless/anony/pull/19)
+
+# v0.3.1
+
+* Fix `anonymised_at` column [#13](https://github.com/gocardless/anony/pull/13)
+
+# v0.3.0
+
+* Support `anonymised_at` column [#9](https://github.com/gocardless/anony/pull/9)
+
+# v0.2.1
+
+* Fix relative require in DefineDeletionStrategy cop [#8](https://github.com/gocardless/anony/pull/8)
+
+# v0.2
+
+* Improve the README [#5](https://github.com/gocardless/anony/pulls/5)
+* Use Rubocop for testing code style [#6](https://github.com/gocardless/anony/pulls/6)
+* Add an [RSpec helper](https://github.com/gocardless/anony/blob/v0.2/README.md#testing) for testing [#7](https://github.com/gocardless/anony/pulls/7)
+
+# v0.1
+
+Initial release.

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in anony.gemspec
+gemspec
+
+gem "activerecord", "~> #{ENV['RAILS_VERSION']}" if ENV["RAILS_VERSION"]
+gem "activesupport", "~> #{ENV['RAILS_VERSION']}" if ENV["RAILS_VERSION"]

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2019 GoCardless
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,451 @@
+# Anony
+
+Anony is a small library that defines how ActiveRecord models should be anonymised for
+deletion purposes.
+
+```ruby
+class User < ActiveRecord::Base
+  include Anony::Anonymisable
+
+  anonymise do
+    overwrite do
+      hex :first_name
+    end
+  end
+end
+```
+```ruby
+irb(main):001:0> user = User.find(1)
+=> #<User id="1" first_name="Alice">
+
+irb(main):002:0> user.anonymise!
+ => #<Anony::Result status="overwritten" fields=[:first_name] error=nil>
+```
+
+For our policy on compatibility with Ruby and Rails versions, see [COMPATIBILITY.md](docs/COMPATIBILITY.md).
+
+## Installation & configuration
+
+This library is distributed as a Ruby gem, and we recommend adding it your Gemfile:
+
+```ruby
+gem "anony"
+```
+
+The library injects itself using a mixin. To add this to a model class, you should include
+`Anony::Anonymisable`:
+
+```ruby
+class User < ActiveRecord::Base
+  include Anony::Anonymisable
+  # ...
+end
+```
+
+Alternatively, if you have a Rails application, you might wish to expose this behaviour
+for all of your models: in which case, you can instead add it to `ApplicationRecord` once:
+
+```ruby
+# app/models/application_record.rb
+class ApplicationRecord < ActiveRecord::Base
+  include Anony::Anonymisable
+end
+```
+
+## Usage
+
+There are two primary ways to use this library: to either overwrite existing fields on a
+record, or to destroy the record altogether.
+
+First, you should establish an `anonymise` block in your model class:
+
+```ruby
+class Employee < ActiveRecord::Base
+  include Anony::Anonymisable
+
+  anonymise do
+  end
+end
+```
+
+If you want to overwrite certain fields on the model, you should use the `overwrite`
+DSL. There are many different ways (known as "strategies") to overwrite your fields (see
+[Field strategies](#field-strategies) below). For now, let's use the `hex` & `nilable` strategies, which
+overwrites fields using `SecureRandom.hex` or sets them to `nil`:
+
+```ruby
+anonymise do
+  overwrite do
+    hex :field_name
+    nilable :nullable_field
+  end
+end
+```
+
+Alternative, you may wish to simply destroy the record altogether when we call
+`#anonymise!` (this is useful if you're anonymising a collection of different models
+together, only some of which need to be destroyed). This can be configured liked so:
+
+```ruby
+anonymise do
+  destroy
+end
+```
+
+Please note that both the `overwrite` and `destroy` strategies cannot be used simultaneously.
+
+Now, given a model instance, we can use the `#anonymise!` method to apply our strategies:
+
+```ruby
+irb(main):001:0> model = Model.find(1)
+=> #<Model id="1" field_name="Previous value" nullable_field="Previous">
+
+irb(main):002:0> model.anonymise!
+ => #<Anony::Result status="overwritten" fields=[:field_name, :nullable_field] error=nil>
+```
+
+ Or, if you were using the `destroy` strategy:
+
+```ruby
+irb(main):002:0> model.anonymise!
+=> #<Anony::Result status="destroyed" fields=nil error=nil>
+```
+
+### Result object
+
+When a model is anonymised, an `Anony::Result` is returned. This allows the library to detail the changes is made and the strategy it used. The result object also contains the errors that may have been raised within Anony, allowing you to handle them elegantly without using the exceptions for flow control.
+
+The result object has 3 attributes:
+
+  * `status` - If the model was `destroyed`, `overwritten`, `skipped` or the operation `failed`
+  * `fields` - In the event the model was `overwritten`, the fields that were updated (excludes timestamps)
+  * `error` - In the event the anonymisation `failed`, then the associated error. Note only rescues the following errors: `ActiveRecord::RecordNotSaved`, `ActiveRecord::RecordNotDestroyed`. Anything else is thrown.
+
+For convenience, the result object can also be queried with `destroyed?`, `overwritten?`, `skipped?` and `failed?`, so that it can be directly interrogated or used in a `switch case` with the `status` property.
+
+### Field strategies
+
+This library ships with a number of built-in strategies:
+
+  * **nilable** overwrites the field with `nil`
+  * **hex** overwrites the field with random hexadecimal characters
+  * **email** overwrites the field with an email
+  * **phone_number** overwrites the field with a dummy phone number
+  * **current_datetime** overwrites the field with `Time.zone.now` (using [ActiveSupport's TimeWithZone](https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html#method-i-now))
+
+### Custom strategies
+
+You can override the default strategies, or add your own ones to make them available
+everywhere, using the `Anony::FieldLevelStrategies.register(name, &block)` method somewhere after
+your application boots (e.g. in a Rails initializer):
+
+```ruby
+Anony::FieldLevelStrategies.register(:reverse) do |original|
+  original.reverse
+end
+
+class Employee < ApplicationRecord
+  include Anony::Anonymisable
+
+  anonymise do
+    overwrite do
+      reverse :first_name
+    end
+  end
+end
+```
+
+> One strategy you might want to override is `:email`, if your application has a more
+> specific replacement. For example, at GoCardless we use an email on the
+> `@gocardless.com` domain so we can ensure any emails accidentally sent to this address
+> would be quickly identified and fixed. `:phone_number` is another strategy that you
+> might wish to replace (depending on your primary location).
+
+You can also use strategies on a case-by-case basis, by honouring the
+`.call(existing_value)` signature:
+
+```ruby
+module OverwriteUUID
+  def self.call(_existing_value)
+    SecureRandom.uuid
+  end
+end
+```
+
+```ruby
+require "overwrite_uuid"
+
+class Manager < ApplicationRecord
+  include Anony::Anonymisable
+
+  anonymise do
+    overwrite do
+      with_strategy OverwriteUUID, :id
+    end
+  end
+end
+```
+
+If your strategy doesn't respond to `.call`, then it will be used as a constant value
+whenever the field is anonymised.
+
+```ruby
+class Manager < ApplicationRecord
+  include Anony::Anonymisable
+
+  anonymise do
+    overwrite do
+      with_strategy 123, :id
+    end
+  end
+end
+```
+
+```
+irb(main):001:0> manager = Manager.first
+ => #<Manager id=42>
+
+irb(main):002:0> manager.anonymise!
+ => #<Anony::Result status="overwritten" fields=[:id] error=nil>
+
+irb(main):003:0> manager
+ => #<Manager id=123>
+```
+
+You can also use a block, which is executed in the context of the model so it can
+access local properties & methods. Blocks take the existing value of the column as the
+only argument:
+
+```ruby
+class Manager < ApplicationRecord
+  include Anony::Anonymisable
+
+  anonymise do
+    overwrite do
+      with_strategy(:first_name) { |name| Digest::SHA2.hexdigest(name) }
+      with_strategy(:last_name) { "previous-name-of-#{id}" }
+    end
+  end
+end
+```
+
+```
+irb(main):001:0> manager = Manager.first
+ => #<Manager id=42>
+
+irb(main):002:0> manager.anonymise!
+=> #<Anony::Result status="overwritten" fields=[:first_name, :last_name] error=nil>
+
+irb(main):003:0> manager
+ => #<Manager first_name="e9ab2800-d4b9-4227-94a7-7f81118d8a8a" last_name="previous-name-of-42">
+```
+
+### Identifying anonymised records
+
+If your model has an `anonymised_at` column, Anony will automatically set that value
+when calling `#anonymise!` (similar to how Rails will modify the `updated_at` timestamp).
+This means you could automatically filter out anonymised records without matching on the
+anonymised values.
+
+Here is an example of adding this column with new tables:
+
+```ruby
+class AddEmployees < ActiveRecord::Migration[6.0]
+  def change
+    create_table(:employees) do |t|
+      # ... the rest of your columns
+      t.column :anonymised_at, :datetime, null: true
+    end
+  end
+end
+```
+
+Here is an example of adding this column to an existing table:
+
+```ruby
+class AddAnonymisedAtToEmployees < ActiveRecord::Migration[6.0]
+  def change
+    add_column(:employees, :anonymised_at, :datetime, null: true)
+  end
+end
+```
+
+Records can then be filtered out like so:
+
+```ruby
+class Employees < ApplicationRecord
+  scope :without_anonymised, -> { where(anonymised_at: nil) }
+end
+```
+
+### Preventing anonymisation
+
+You might have a need to preserve model data in some (or all) circumstances. Anony exposes
+the `skip_if` DSL for expressing this preference, which runs the given block before
+attempting any strategy.
+
+* If the block returns _truthy_, anonymisation is skipped.
+* If the block returns _falsey_, anonymisation continues.
+
+```ruby
+class Manager
+  def should_not_be_anonymised?
+    id == 1 # The first manager must be kept
+  end
+
+  anonymise do
+    skip_if { should_not_be_anonymised? }
+  end
+end
+```
+
+The result object will indicate the model was skipped:
+
+```
+irb(main):001:0> manager = Manager.find(1)
+ => #<Manager id=1>
+
+irb(main):002:0> manager.anonymise!
+=> #<Anony::Result status="skipped" fields=[] error=nil>
+```
+
+## Incomplete field strategies
+
+One of the goals of this library is to ensure that your field strategies are _complete_,
+i.e. that the anonymisation behaviour of the model is always correct, even when database
+columns are added/removed or the contents of those columns changes.
+
+As such, Anony will validate your model configuration when you try to anonymise the
+model (unfortunately this cannot be safely done at boot as the database might not be
+available). If your configuration is incomplete, calling `#anonymise!` will raise a
+`FieldsException` and will not return an `Anony:Result` object. This is perceived
+to a critical error as anony cannot safely anonymise the model.
+
+```
+irb(main):001:0> manager = Manager.find(1)
+ => #<Manager id=1>
+
+irb(main):002:0> manager.anonymise!
+Anony::FieldException (Invalid anonymisation strategy for field(s) [:username])
+```
+
+We recommend adding a test for each model that you anonymise (see [Testing](#testing)
+below).
+
+### Adding new columns
+
+Anony will fail if you try to anonymise a model without specifying a
+strategy for all of the columns (to ensure that anonymisation rules aren't missed over
+time). However, it's fine to define a strategy for a column
+that hasn't yet been added.
+
+This means that, in order to add a new column, you should:
+
+  1. Define a strategy for the new column (e.g. `nilable :new_column`)
+  2. Add the column in a database migration.
+
+> At GoCardless we do zero-downtime deploys so we would deploy the first change before
+> then deploying the migration.
+
+### Excluding common Rails columns
+
+Rails applications typically have an `id`, `created_at` and `updated_at` column on all new
+tables by default. To avoid anonymising these fields (and thus prevent a
+`FieldsException`), they can be globally ignored:
+
+```ruby
+# config/initializers/anony.rb
+
+Anony::Config.ignore_fields(:id, :created_at, :updated_at)
+```
+
+By default, `Config.ignore_fields` is an empty array and all fields are considered
+anonymisable.
+
+## Testing
+
+This library ships with a set of useful RSpec examples for your specs. Just require them
+somewhere before running your spec:
+
+```ruby
+require "anony/rspec_shared_examples"
+```
+
+```ruby
+# spec/models/employee_spec.rb
+
+RSpec.describe Employee do
+  # We use FactoryBot at GoCardless, but
+  # however you setup a model instance is fine
+  subject { FactoryBot.build(:employee) }
+
+  # If you just anonymise fields normally
+  it_behaves_like "overwritten anonymisable model"
+
+  # Or, if your anonymised model should be skipped
+  it_behaves_like "skipped anonymisable model"
+
+  # Or, if you anonymise by destroying the record
+  it_behaves_like "destroyed anonymisable model"
+end
+```
+
+You can also override the subject _inside_ the shared example if it helps (e.g. if you
+need to persist the record before anonymising it):
+
+```ruby
+RSpec.describe Employee do
+  it_behaves_like "anonymisable model with destruction" do
+    subject { FactoryBot.create(:employee) }
+  end
+end
+```
+
+If you're not using RSpec, or want more control over the tests, Anony also exposes an
+instance method called `#valid_anonymisation?`. A simple spec would be:
+
+```ruby
+RSpec.describe Employee do
+  subject { described_class.new }
+
+  it { is_expected.to be_valid_anonymisation }
+end
+```
+
+## Integration with Rubocop
+
+At GoCardless, we use Rubocop heavily to ensure consistency in our applications. This
+library includes some Rubocop cops, which can be used by adding `anony/cops` to the
+`require` list in your `.rubocop.yml`:
+
+```yml
+require:
+  - anony/cops
+```
+
+### `Lint/DefineDeletionStrategy`
+
+This cop ensures that all models in your application have defined an `anonymise` block.
+The output looks like this:
+
+```
+app/models/employee.rb:7:1: W: Lint/DefineDeletionStrategy:
+  Define .anonymise for Employee, see https://github.com/gocardless/anony/blob/master/README.md for details:
+  class Employee < ApplicationRecord ...
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+If your models do not inherit from `ApplicationRecord`, you can specify their superclass
+in your `.rubocop.yml`:
+
+```yml
+Lint/DefineDeletionStrategy:
+  ModelSuperclass: Acme::Record
+```
+
+## License & Contributing
+
+* Anony is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+* Bug reports and pull requests are welcome on GitHub at https://github.com/gocardless/anony.
+
+GoCardless ♥ open source. If you do too, come [join us](https://gocardless.com/about/jobs).