declarative_policy 1.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c08845902bc432f4c737ba76d2b9a5f0cc456fed1d0f26353755146ab49b2a1
-  data.tar.gz: 0f64e5d7707dff73572484cd700b529704f4d41dfd0b1972c8d675e4281d3582
+  metadata.gz: 704af6c0500c00a0e6c6797dd5b496c098db86f33ccc1ef2496be37e43b33e03
+  data.tar.gz: 2236adb02dbee28b6565fc72541fe2fbee5a087ef15cc2fe1f0d060ce1eece13
 SHA512:
-  metadata.gz: 0b5bc3cfd66be62b483aa8beb673b8b858121a18a0dcb64bd9f6fa79d268ebf3ddb566ede84c1032beac05bc81f6fa8f0642e846a42f6bcf21083eb04de7fa2c
-  data.tar.gz: fabb732587403af0e1cfe8cfcc25033f0d8ccaee066e8310bd0bacf38fba052758e97e3aedbc42e6c62f898a07eaf598885a731f4b80fa9fdf1fe321dfa2901b
+  metadata.gz: c3841495e1922ae72f704524e40ca080da4838cfe075d401350212f5b31f116f6003aa3e371d2a0084a11986b4745bb82946ad84b61247a19b59470a26e24755
+  data.tar.gz: f3f0d97ba2b9e56079d5307c135ec2b15c73759661f32e6cda2db44ab0fa21002598725cf0c762ca85c0580ae1c5b7c397115f185ec94c9da600cfaf19f6e590

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+2.0.0:
+
+- Drop explicit support for Ruby 2.6 and 2.7 by removing those versions from
+  the CI matrix. These Ruby versions are now past EOL.
+- Rename default condition scope name to `:user_and_subject`
+- Clarify the use of `User` and `Subject` in README and documentation
+- Update `ruby-git` in Gemfile.lock
+
+1.1.1:
+
+- Define development dependencies
+
+1.1.0:
+
+- Add cache invalidation API: `DeclarativePolicy.invalidate(cache, keys)`
+- Include actor class name in cache key
+
+1.0.1:
+
+- Added unit level tests for `lib/declarative_policy/rule.rb`

data/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+## Developer Certificate of Origin and License
+
+By contributing to GitLab B.V., you accept and agree to the following terms and
+conditions for your present and future contributions submitted to GitLab B.V.
+Except for the license granted herein to GitLab B.V. and recipients of software
+distributed by GitLab B.V., you reserve all right, title, and interest in and to
+your Contributions.
+
+All contributions are subject to the Developer Certificate of Origin and license set out at [docs.gitlab.com/ce/legal/developer_certificate_of_origin](https://docs.gitlab.com/ce/legal/developer_certificate_of_origin).
+
+_This notice should stay as the first item in the CONTRIBUTING.md file._
+
+## Code of conduct
+
+As contributors and maintainers of this project, we pledge to respect all people
+who contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual
+language or imagery, derogatory comments or personal attacks, trolling, public
+or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct. Project maintainers who do not follow the
+Code of Conduct may be removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior can be
+reported by emailing contact@gitlab.com.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org), version 1.1.0,
+available at [https://contributor-covenant.org/version/1/1/0/](https://contributor-covenant.org/version/1/1/0/).
+

data/LICENSE.txt

@@ -1,6 +1,9 @@
 The MIT License (MIT)
 
-Copyright (c) 2021 Alex Kalderimis
+Copyright (c) 2021 GitLab
+
+The original author of this library is [Jeanine Adkisson](http://jneen.net),
+and copyright is held by GitLab.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,5 +1,7 @@
 # `DeclarativePolicy`: A Declarative Authorization Library
 
+[![Gem Version](https://badge.fury.io/rb/declarative_policy.svg)](https://badge.fury.io/rb/declarative_policy)
+
 This library provides a DSL for writing authorization policies.
 
 It can be used to separate logic from permissions, and has been
@@ -18,14 +20,72 @@ gem 'declarative_policy'
 
 And then execute:
 
-    $ bundle install
+```plain
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install declarative_policy
+```plain
+$ gem install declarative_policy
+```
 
-## Usage
+## Example
 
+```ruby
+require 'declarative_policy'
+
+class User
+  attr_reader :name
+
+  def initialize(name:)
+    @name = name
+  end
+end
+
+class Vehicle
+  def initialize(owner:, trusted: [])
+    @owner = owner
+    @trusted = trusted
+  end
+
+  def owner?(user)
+    @owner.name == user.name
+  end
+
+  def trusted?(user)
+    @owner.name == user.name || @trusted.detect { |t| t.name == user.name }
+  end
+end
+
+class VehiclePolicy < DeclarativePolicy::Base
+  condition(:owns) { @subject.owner?(@user) }
+  condition(:trusted) { @subject.trusted?(@user) }
+
+  rule { owns }.enable :sell_vehicle
+  rule { trusted }.enable :drive_vehicle
+end
+
+jack = User.new(name: 'jack')
+jill = User.new(name: 'jill')
+jacks_vehicle = Vehicle.new(owner: jack, trusted: [jill])
+jills_vehicle = Vehicle.new(owner: jill, trusted: [jack])
+
+puts "Jack can drive Jack's vehicle? -> #{DeclarativePolicy.policy_for(jack, jacks_vehicle).can?(:drive_vehicle)}"
+puts "Jack can drive Jill's vehicle? -> #{DeclarativePolicy.policy_for(jack, jills_vehicle).can?(:drive_vehicle)}"
+puts "Jack can sell Jack's vehicle? -> #{DeclarativePolicy.policy_for(jack, jacks_vehicle).can?(:sell_vehicle)}"
+puts "Jack can sell Jill's vehicle? -> #{DeclarativePolicy.policy_for(jack, jills_vehicle).can?(:sell_vehicle)}"
+```
+
+```plain
+$ ruby example.rb
+Jack can drive Jack's vehicle? -> true
+Jack can drive Jill's vehicle? -> true
+Jack can sell Jack's vehicle? -> true
+Jack can sell Jill's vehicle? -> false
+```
+
+## Usage
 
 The core abstraction of this library is a `Policy`. Policies combine:
 
@@ -34,9 +94,12 @@ The core abstraction of this library is a `Policy`. Policies combine:
 
 This library exists to determine the truth value of statements of the form:
 
+```plain
+User Predicate [Subject]
 ```
-Subject Predicate [Object]
-```
+
+Renaming `User` to `Actor` and `Subject` to `Resource` is discussed in
+[this issue](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/issues/6).
 
 For example:
 
@@ -61,15 +124,15 @@ class VehiclePolicy < DeclarativePolicy::Base
   # expensive rules can have 'score'. Higher scores are 'more expensive' to calculate
   condition(:owns, score: 0) { @subject.owner == @user }
   condition(:has_access_to, score: 3) { @subject.owner.trusts?(@user) }
-  condition(:intoxicated, score: 5) { @user.blood_alcohol < laws.max_blood_alcohol }
-  
+  condition(:intoxicated, score: 5) { @user.blood_alcohol > laws.max_blood_alcohol }
+
   # conclusions we can draw:
   rule { owns }.enable :drive_vehicle
   rule { has_access_to }.enable :drive_vehicle
   rule { ~old_enough_to_drive }.prevent :drive_vehicle
   rule { intoxicated }.prevent :drive_vehicle
   rule { ~has_driving_license }.prevent :drive_vehicle
-  
+
   # we can use methods to abstract common logic
   def laws
     @subject.registration.country.driving_laws
@@ -116,20 +179,26 @@ policy = DeclarativePolicy.policy_for(user, car, cache: cache)
 policy.can?(:drive_vehicle)
 ```
 
-For more usage details, see the [documentation](docs/usage.md).
+For more usage details, see the [documentation](doc).
 
 ## Development
 
-After checking out the repository, run `bin/setup` to install dependencies.
+After checking out the repository, run `bundle install` 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.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Additional Reading Material
+
+More details on policies and custom roles can be found in the following pages:
+- [Development Process for the DeclarativePolicy framework](https://docs.gitlab.com/ee/development/policies.html)
+- [Custom Roles docs](https://docs.gitlab.com/ee/development/permissions/custom_roles.html)
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at
-https://gitlab.com/gitlab-org/declarative-policy. This project is intended to be
+Bug reports and merge requests are welcome on GitLab at
+https://gitlab.com/gitlab-org/ruby/gems/declarative-policy. This project is intended to be
 a safe, welcoming space for collaboration, and contributors are expected to
 adhere to the [GitLab code of conduct](https://about.gitlab.com/community/contribute/code-of-conduct/).
 

data/{declarative_policy.gemspec → declarative-policy.gemspec}

@@ -5,8 +5,8 @@ require_relative 'lib/declarative_policy/version'
 Gem::Specification.new do |spec|
   spec.name          = 'declarative_policy'
   spec.version       = DeclarativePolicy::VERSION
-  spec.authors       = ['Jeanine Adkisson', 'Alexis Kalderimis']
-  spec.email         = ['akalderimis@gitlab.com']
+  spec.authors       = ['group::authorization']
+  spec.email         = ['engineering@gitlab.com']
 
   spec.summary       = 'An authorization library with a focus on declarative policy definitions.'
   spec.description   = <<~DESC
@@ -17,20 +17,35 @@ Gem::Specification.new do |spec|
 
     This library is in production use at GitLab.com
   DESC
-  spec.homepage      = 'https://gitlab.com/gitlab-org/declarative-policy'
+  spec.homepage      = 'https://gitlab.com/gitlab-org/ruby/gems/declarative-policy'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0.0')
 
   spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://gitlab.com/gitlab-org/declarative-policy'
-  spec.metadata['changelog_uri'] = 'https://gitlab.com/gitlab-org/declarative-policy/-/blobs/master/CHANGELOG.md'
+  spec.metadata['source_code_uri'] = 'https://gitlab.com/gitlab-org/ruby/gems/declarative-policy'
+  spec.metadata['changelog_uri'] = 'https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/blob/main/CHANGELOG.md'
+
+  spec.metadata['rubygems_mfa_required'] = 'false'
 
   # 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)/}) }
+    %w[
+      *.gemspec
+      lib/**/*.rb
+      *.{md,txt}
+      doc/**/*
+    ].flat_map { |pattern| Dir.glob(pattern) }
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
+
+  # Development dependencies:
+  spec.add_development_dependency 'benchmark-ips', '~> 2.12'
+  spec.add_development_dependency 'gitlab-dangerfiles', '~> 3.8'
+  spec.add_development_dependency 'gitlab-styles', '~> 12.0'
+  spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'rake', '~> 12.0'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  spec.add_development_dependency 'rspec-parameterized', '~> 1.0'
 end

data/doc/caching.md

@@ -1,4 +1,302 @@
 # Caching
 
-**TODO**: see https://gitlab.com/gitlab-org/declarative-policy/-/issues/11
+This library deals with making observations about the state of
+a system (usually performing I/O, such as making a database query),
+and combining these facts into logical propositions.
 
+In order to make this performant, the library transparently caches repeated
+observations of conditions. Understanding how caching works is useful for
+designing good policies, using them effectively.
+
+## What is cached?
+
+If a policy is instantiated with a cache, then the following things will be
+stored in it:
+
+- Policy instances (there will only ever be one policy per `user/subject` pair
+  for the lifetime of the cache).
+- Condition results
+
+The correctness of these cached values depends on the correctness of the
+cache-keys. We assume the objects in your domain have a `#id` method that
+fully captures the notion of object identity. See [Cache keys](#cache-keys) for
+details. All cache keys begin with `"/dp/"`.
+
+Policies themselves cache the results of the abilities they compute.
+
+Policies distinguish between facts based on the type of the fact:
+
+- Boolean facts: implemented with `condition`.
+- Abilities: implemented with `rule` blocks.
+- Non-boolean facts: implemented by policy instance methods.
+
+For example, consider a policy for countries:
+
+```ruby
+class CountryPolicy < DeclarativePolicy::Base
+  condition(:citizen) { @user.citizen_of?(country.country_code) }
+  condition(:eu_citizen, scope: :user) { @user.citizen_of?(*Unions::EU) }
+  condition(:eu_member, scope: :subject) { Unions::EU.include?(country.country_code) }
+
+  condition(:has_visa_waiver)    { country.visa_waivers.any? { |c| @user.citizen_of?(c) } }
+  condition(:permanent_resident) { visa_category == :permanent }
+  condition(:has_work_visa)      { visa_category == :work }
+  condition(:has_current_visa)   { has_visa_waiver? || current_visa.present? }
+  condition(:has_business_visa)  { has_visa_waiver? || has_work_visa? || visa_category == :business }
+
+  condition(:full_rights, score: 20) { citizen? || permanent_resident? }
+  condition(:banned) { country.banned_list.include?(@user) }
+
+  rule { eu_member & eu_citizen }.enable :freedom_of_movement
+  rule { full_rights | can?(:freedom_of_movement) }.enable :settle
+  rule { can?(:settle) | has_current_visa }.enable :enter_country
+  rule { can?(:settle) | has_business_visa }.enable :attend_meetings
+  rule { can?(:settle) | has_work_visa }.enable :work
+  rule { citizen }.enable :vote
+  rule { ~citizen & ~permanent_resident }.enable :apply_for_visa
+  rule { banned }.prevent :enter_country, :apply_for_visa
+
+  def current_visa
+    return @current_visa if defined?(@current_visa)
+
+    @current_visa = country.active_visas.find_by(applicant: @user)
+  end
+
+  def visa_category
+    current_visa&.category
+  end
+
+  def country
+    @subject
+  end
+end
+```
+
+This is a reasonably realistic policy - there are a few pieces of state (the
+country, the list of visa waiver agreements, the list of citizenships the user
+holds, the kind of visa the user has, if they have one, the current list of
+banned users), and these are combined to determine a range of abilities (whether
+one can visit or live in or vote in a certain country). Importantly, these
+pieces of information are re-used between abilities - the citizenship status is
+relevant to all abilities, whereas the banned list is only considered on entry
+and when applying for a new visa).
+
+If we imagine that some of these operations are reasonably expensive (fetching
+the current visa status, or checking the banned list, for example), then it
+follows that we really care about avoiding re-computation of these facts. In the
+policy above we can see a few strategies that are taken to avoid this:
+
+- Conditions are re-used liberally.
+- Non-boolean facts are cached at the policy level.
+
+## Re-using conditions
+
+Rules can and should re-use conditions as much as possible. Condition
+observations are cached automatically, so referring to the same condition in
+multiple rules is encouraged. Conditions can also refer to other conditions by
+using the predicate methods that are created for them (see `full_rights`, which
+refers to the `:citizen` condition as `citizen?`).
+
+Note that referring to conditions inside other conditions can be DRY, but it
+limits the ability of the library to optimize the steps (see
+[optimization](./optimization.md)). For example in the `:has_current_visa`
+condition, the sub-conditions will always be tested in the order
+`has_visa_waiver` then `current_visa.present?`. It is recommended not to rely
+heavily on this kind of abstraction.
+
+## Re-using rules
+
+Entire rule-sets can be re-used with `can?`. This is a form of logical
+implication where a previous conclusion can be used in a further rule. Examples
+of this here are `can?(:settle)` and `can?(:freedom_of_movement)`. This can
+prevent having to repeat long groups of conditions in rule definitions. This
+abstraction is transparent to the optimizer.
+
+## Non-boolean values must be managed manually
+
+The condition `has_current_visa` and the more specific
+`has_{work,business}_visa` all refer to the same piece of state - the
+`#current_visa`. Since this is not a boolean (but is here a database record with
+a `#category` attribute), this cannot be a condition, but must be managed by the
+policy itself.
+
+The best approach here is to use normal Ruby methods and instance variables for
+such values. The policy instances themselves are cached, so that any two
+invocations of `DeclarativePolicy.policy_for(user, subject)` with identical
+`user` and `subject` arguments will always return the same policy object. This
+means instance variables stored on the policy will be available for the lifetime
+of the cache.
+
+Methods can be used for the usual reasons of clarity (such as referring to the
+`@subject` as `country`) and brevity (such as `visa_category`).
+
+## Cache lifetime
+
+The cache is provided by the user of the library, passing it to the
+`.policy_for` method. For example:
+
+```ruby
+DeclarativePolicy.policy_for(user, country, cache: some_cache_value)
+```
+
+The object only needs to implement the following methods:
+
+- `cache[key: String] -> Boolean?`: Fetch the cached value
+- `cache.key?(key: String) -> Boolean`: Test if the key is cached
+- `cache[key: String] = Boolean`: Cache a value
+
+Obviously, a `HashMap` will work just fine, but so will a wrapper around a
+[`Concurrent::Map`](https://ruby-concurrency.github.io/concurrent-ruby/1.1.4/Concurrent/Map.html),
+or even a map that delegates to Redis with a TTL for each key, so long as the
+object supports these methods. Keys are never deleted by the library, and values
+are only computed if the key is not cached, so it is up to the application code
+to determine the life-time of each key.
+
+Clearly, cache-invalidation is a hard problem. At GitLab we share a single cache
+object for each request - so any single request can freely request a permission
+check multiple times (or even compute related abilities, such as
+`:enter_country` and `:settle`) and know that no work is duplicated. This
+allows developers to reason declaratively, and add permission checks where
+needed, without worrying about performance.
+
+## Cache sharing: scopes
+
+Not all conditions are equally specific. The condition `citizen` refers to
+both the user and the country, and so can only be used when checking both the
+user and the country. We say that this is the `normal` scope.
+
+This is not always true however. Sometimes a condition refers only to the user.
+For example, above we have two conditions: `eu_citizen` and `eu_member`:
+
+```ruby
+  condition(:eu_citizen, scope: :user) { @user.citizen_of?(*Unions::EU) }
+  condition(:eu_member, scope: :subject) { Unions::EU.include?(country.country_code) }
+```
+
+`eu_citizen` refers only to the user, and `eu_member` refers only to the
+country.
+
+If we have a user that wants to enter multiple countries on a grand European
+tour, we could check this with:
+
+```ruby
+itinerary.countries.all? { |c| DeclarativePolicy.policy_for(user, c).allowed?(:enter_country) }
+```
+
+If `eu_citizen` were declared with the `normal` scope, then this would have a lot of cache
+misses. By using the `:user` scope on `eu_citizen`, we only check EU citizenship
+once.
+
+Similarly for `eu_member`, if a team of football players want to visit a
+country, then we could check this with:
+
+```ruby
+team.players.all? { |user| DeclarativePolicy.policy_for(user, country).allowed?(:enter_country) }
+```
+
+Again, by declaring `eu_member` as having the `:subject` scope, this ensures we
+only check EU membership once, not once for each football player.
+
+The last scope is `:global`, used when the condition is universally true:
+
+```ruby
+  condition(:earth_destroyed_by_meteor, scope: global) { !Planet::Earth.exists? }
+
+  rule { earth_destroyed_by_meteor }.prevent_all
+```
+
+In this case, it doesn't matter who the user is or even where they are going:
+the condition will be computed once (per cache lifetime) for all combinations.
+
+Because of the implications for sharing, the scope determines the
+[`#score`](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/blob/2ab9dbdf44fb37beb8d0f7c131742d47ae9ef5d0/lib/declarative_policy/condition.rb#L58-77) of
+the condition (if not provided explicitly). The intention is to prefer values we
+are more likely (all other things being equal) to re-use:
+
+- Conditions we have already cached get a score of `0`.
+- Conditions that are in the `:global` scope get a score of `2`.
+- Conditions that are in the `:user` or `:subject` scopes get a score of `8`.
+- Conditions that are in the `:user_and_subject` scope get a score of `16`.
+
+Bear helper-methods in mind when defining scopes. While the instance level cache
+for non-boolean values would not be shared, as long as the derived condition is
+shared (for example by being in the `:user` scope, rather than the `:user_and_subject`
+scope), helper-methods will also benefit from improved cache hits.
+
+### Preferred scope
+
+In the example situations above (a single user visiting many countries, or a
+football team visiting one country), we know which is more likely to be useful,
+the `:subject` or the `:user` scope. We can inform the optimizer of this
+by setting `DeclarativePolicy.preferred_scope`.
+
+To do this, check the abilities within a block bounded
+by [`DeclarativePolicy.with_preferred_scope`](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/blob/481c322a74f76c325d3ccab7f2f3cc2773e8168b/lib/declarative_policy/preferred_scope.rb#L7-13).
+For example:
+
+```ruby
+cache = {}
+
+# preferring to run user-scoped conditions
+DeclarativePolicy.with_preferred_scope(:user) do
+  itinerary.countries.all? do |c|
+    DeclarativePolicy.policy_for(user, c, cache: cache).allowed?(:enter_country)
+  end
+end
+
+# preferring to run subject-scoped conditions
+DeclarativePolicy.with_preferred_scope(:subject) do
+  team.players.all? do |player|
+    DeclarativePolicy.policy_for(player, c, cache: cache).allowed?(:enter_country)
+  end
+end
+
+```
+
+When we set `preferred_scope`, this reduces the default score for conditions in
+that scope, so that they are more likely to be executed first. Instead of `8`,
+they are given a default score of `4`.
+
+## Cache keys
+
+In order for an object to be cached, it should be able to identify itself
+with a suitable cache key. A good cache key will identify an object, without
+containing irrelevant information - a database `#id` is perfect, and this
+library defaults to calling an `#id` method on objects, falling back to
+`object_id`.
+
+Relying on `object_id` is not recommended since otherwise equivalent objects
+have different `object_id` values, and using `object_id` will not get optimal caching. All
+policy subjects should implement `#id` for this reason. `ActiveRecord` models
+with an `id` primary ID attribute do not need any extra configuration.
+
+Please see: [`DeclarativePolicy::Cache`](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/blob/main/lib/declarative_policy/cache.rb).
+
+## Cache invalidation
+
+Generally, cache invalidation is best avoided. It is very hard to get right, and
+relying on it opens you up to subtle but pernicious bugs that are hard to
+reproduce and debug.
+
+The best strategy is to run all permission checks upfront, before mutating any
+state that might change a permission computation. For instance, if you want to
+make a user an administrator, then check for permission **before** assigning
+administrator privileges.
+
+However, it isn't always possible to avoid needing to mark certain parts of the
+cached state as dirty (in need of re-computation). If this is needed, then you
+can call the `DeclarativePolicy.invalidate(cache, keys)` method. This takes an
+enumerable of dirty keys, and:
+
+- removes the cached condition results from the cache
+- marks the abilities that depend on those conditions as dirty, and in need of
+  re-computation.
+
+The responsibility for determining which cache-keys are dirty falls on the
+client. You could, for example, do this by observing which keys are added to the
+cache (knowing that condition keys all start with `"/dp/condition/"`), or by
+scanning the cache for keys that match a heuristic.
+
+This method is the only place where the `#delete` method is called on the cache.
+If you do not call `.invalidate`, there is no need for the cache to implement
+`#delete`.