declarative_policy 1.0.0

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/danger/plugins/project_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Danger
+  # Project specific configuration
+  class ProjectHelper < ::Danger::Plugin
+    LOCAL_RULES ||= %w[
+      changelog
+      documentation
+    ].freeze
+
+    CI_ONLY_RULES ||= %w[
+      roulette
+    ].freeze
+
+    MESSAGE_PREFIX = '==>'
+
+    # First-match win, so be sure to put more specific regex at the top...
+    # rubocop: disable Style/RegexpLiteral
+    CATEGORIES = {
+      %r{\A(\.gitlab-ci\.yml\z|\.gitlab/ci)} => :engineering_productivity,
+      %r{\Alefthook.yml\z} => :engineering_productivity,
+      %r{\A\.editorconfig\z} => :engineering_productivity,
+      %r{Dangerfile\z} => :engineering_productivity,
+      %r{\A(danger/|tooling/danger/)} => :engineering_productivity,
+      %r{\A?scripts/} => :engineering_productivity,
+      %r{\Atooling/} => :engineering_productivity,
+      %r{(CODEOWNERS)} => :engineering_productivity,
+      %r{\A(Gemfile|Gemfile.lock|Rakefile)\z} => :backend,
+      %r{\A\.rubocop((_manual)?_todo)?\.yml\z} => :backend,
+      %r{\.rb\z} => :backend,
+      %r{(
+        \.(md|txt)\z |
+        \.markdownlint\.json
+      )}x => :docs
+    }.freeze
+    # rubocop: enable Style/RegexpLiteral
+
+    def changes_by_category
+      helper.changes_by_category(CATEGORIES)
+    end
+
+    def changes
+      helper.changes(CATEGORIES)
+    end
+
+    def rule_names
+      helper.ci? ? LOCAL_RULES | CI_ONLY_RULES : LOCAL_RULES
+    end
+
+    def project_name
+      # 'declarative-policy'
+      # TODO: roulette uses the project name to find reviewers, but the gitlab team
+      # directory currently does not have any team members assigned to the declarative-policy
+      # project. We thus are piggybacking on 'gitlab' for now.
+      'gitlab'
+    end
+  end
+end

data/danger/roulette/Dangerfile

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'digest/md5'
+
+MESSAGE = <<MARKDOWN
+## Reviewer roulette
+
+Changes that require review have been detected! A merge request is normally
+reviewed by both a reviewer and a maintainer.
+MARKDOWN
+
+CATEGORY_TABLE_HEADER = <<MARKDOWN
+
+To spread load more evenly across eligible reviewers, Danger has picked a
+candidate for each review slot, based on their timezone. Feel free to
+[override these selections](https://about.gitlab.com/handbook/engineering/projects/#gitlab) if
+you think someone else would be better-suited or use the
+[GitLab Review Workload Dashboard](https://gitlab-org.gitlab.io/gitlab-roulette/) to find other
+available reviewers.
+
+To read more on how to use the reviewer roulette, please take a look at the
+[Engineering workflow](https://about.gitlab.com/handbook/engineering/workflow/#basics) and
+[code review guidelines](https://docs.gitlab.com/ee/development/code_review.html). You may
+consider assigning a reviewer or maintainer who is
+a [domain expert](https://about.gitlab.com/handbook/engineering/projects/#gitlab) for
+the `DeclarativePolicy` library.
+
+Once you've decided who will review this merge request, assign them as a reviewer!
+Danger does not automatically notify them for you.
+
+| Category | Reviewer | Maintainer |
+| -------- | -------- | ---------- |
+MARKDOWN
+
+UNKNOWN_FILES_MESSAGE = <<MARKDOWN
+
+These files couldn't be categorised, so Danger was unable to suggest a reviewer.
+Please consider creating a merge request
+to [add support](https://gitlab.com/gitlab-org/gitlab/blob/master/tooling/danger/project_helper.rb)
+for them.
+MARKDOWN
+
+OPTIONAL_REVIEW_TEMPLATE = '%{role} review is optional for %{category}'
+NOT_AVAILABLE_TEMPLATE = 'No %{role} available'
+
+def note_for_spins_role(spins, role)
+  spins.each do |spin|
+    note = note_for_spin_role(spin, role)
+
+    return note if note
+  end
+
+  format(NOT_AVAILABLE_TEMPLATE, role: role)
+end
+
+def note_for_spin_role(spin, role)
+  if spin.optional_role == role
+    return format(OPTIONAL_REVIEW_TEMPLATE, role: role.capitalize, category: helper.label_for_category(spin.category))
+  end
+
+  spin.public_send(role)&.markdown_name(author: roulette.team_mr_author) # rubocop:disable GitlabSecurity/PublicSend
+end
+
+def markdown_row_for_spins(category, spins_array)
+  reviewer_note = note_for_spins_role(spins_array, :reviewer)
+  maintainer_note = note_for_spins_role(spins_array, :maintainer)
+
+  "| #{helper.label_for_category(category)} | #{reviewer_note} | #{maintainer_note} |"
+end
+
+changes = project_helper.changes_by_category
+
+# Ignore any files that are known but uncategorized. Prompt for any unknown files
+changes.delete(:none)
+# To reinstate roulette for documentation, remove this line.
+changes.delete(:docs)
+# No special review for changelog needed and changelog was never a label.
+changes.delete(:changelog)
+# No special review for feature flags needed.
+changes.delete(:feature_flag)
+categories = changes.keys.to_set.delete(:unknown)
+
+if changes.any?
+  project = project_helper.project_name
+
+  random_roulette_spins = roulette.spin(project, categories, timezone_experiment: false)
+
+  rows = random_roulette_spins.map do |spin|
+    markdown_row_for_spins(spin.category, [spin])
+  end
+
+  markdown(MESSAGE)
+  markdown(CATEGORY_TABLE_HEADER + rows.join("\n")) unless rows.empty?
+
+  unknown = changes.fetch(:unknown, [])
+  markdown(UNKNOWN_FILES_MESSAGE + helper.markdown_list(unknown)) unless unknown.empty?
+end

data/declarative_policy.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+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.summary       = 'An authorization library with a focus on declarative policy definitions.'
+  spec.description   = <<~DESC
+    This library provides an authorization framework with a declarative DSL
+
+    With this library, you can write permission policies that are separate
+    from business logic.
+
+    This library is in production use at GitLab.com
+  DESC
+  spec.homepage      = 'https://gitlab.com/gitlab-org/declarative-policy'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.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'
+
+  # 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.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+end

data/doc/caching.md

@@ -0,0 +1,4 @@
+# Caching
+
+**TODO**: see https://gitlab.com/gitlab-org/declarative-policy/-/issues/11
+

data/doc/configuration.md

@@ -0,0 +1,78 @@
+# Configuration
+
+This library is generally configured by writing policies that match
+the look-up rules for domain objects (see: [defining policies](./defining-policies.md)).
+
+## Configuration blocks
+
+This library can be configured using `DeclarativePolicy.configure` and
+`DeclarativePolicy.configure!`. Both methods take a block, and they differ only
+in that `.configure!` ensures that the configuration is pristine, and
+discards any previous configuration, and `configure` can be called multiple
+times.
+
+## Handling `nil` values
+
+By default, all permission checks on `nil` values are denied. This is
+controlled by `DeclarativePolicy::NilPolicy`, which is implemented as:
+
+```ruby
+module DeclarativePolicy
+  class NilPolicy < DeclarativePolicy::Base
+    rule { default }.prevent_all
+  end
+end
+```
+
+If you want to handle `nil` values differently, then you can define your
+own `nil` policy, and configure it to be used in a configuration block:
+
+```ruby
+DeclarativePolicy.configure do
+  nil_policy MyNilPolicy
+end
+```
+
+## Named policies
+
+Normally policies are determined by looking up matching policy definitions
+based on the class of the value. `Symbol` values are treated specially, and
+these define **named policies**.
+
+To define a named policy, use a configuration block:
+
+```ruby
+DeclarativePolicy.configure do
+  named_policy :global, MyGlobalPolicy
+end
+```
+
+Then it can be used by passing the `:global` symbol as the value in a permission
+check:
+
+```
+policy = DeclarativePolicy.policy_for(the_user, :global)
+policy.allowed?(:some_ability)
+```
+
+This can be useful where there is no object of the permission check (that is,
+the predicate is **intransitive**). An example might be `:can_log_in`, where
+there is no suitable object, and the identity of the user is fully sufficient to
+determine the permission check.
+
+Using `:global` is a convention, but any policy name can be used.
+
+## Name transformation
+
+By default, policy classes are expected to be named for the domain classes, with
+a `Policy` suffix. So a domain class of `Foo` would resolve to a `FooPolicy`.
+
+This logic can be customized by specifying the `name_transformation` rule. To
+instead have all policies be placed in a `Policies` namespace, so that `Foo`
+would have its policy at `Policies::Foo`, we can configure that with:
+
+```ruby
+DeclarativePolicy.configure do
+  name_transformation { |name| "Policies::#{name}" }
+end
+```

data/doc/defining-policies.md

@@ -0,0 +1,185 @@
+# Defining policies
+
+A policy is a set of conditions and rules for domain objects. They are defined
+using a DSL, and mapped to domain objects by class name.
+
+## Class name determines policy choice
+
+If there is a domain class `Foo`, then we can link it to a policy by defining a
+class `FooPolicy`. This class can be placed anywhere, as long as it is loaded
+before the call to `DeclarativePolicy.policy_for`.
+
+Our recommendation for large applications, such as Rails apps, is to add a new
+top-level application directory: `app/policies`, and place all policy
+definitions in there. If you have an `Invoice` model at `app/models/invoice.rb`,
+then you would create an `InvoicePolicy` at `app/policies/invoice_policy.rb`.
+
+## Invocation
+
+We evaluate policies by instantiating them with `DeclarativePolicy::policy_for`,
+and then evaluating them with `DeclarativePolicy::Base#allowed?`.
+
+You may wish to define a method to abstract policy evaluation. Something like:
+
+```ruby
+def allowed?(user, ability, object)
+  opts = { cache: Cache.current_cache } # re-using a cache between checks eliminates duplication of work
+  policy = DeclarativePolicy.policy_for(user, object, opts)
+  policy.allowed?(ability)
+end
+```
+
+We will assume the presence of such a method below.
+
+## Defining rules in the DSL
+
+The DSL has two primary parts: defining **conditions** and **rules**.
+
+For example, imagine we have a data model containing vehicles and users, and we
+want to know if a user can drive a vehicle. We need a `VehiclePolicy`:
+
+```ruby
+class VehiclePolicy < DeclarativePolicy::Base
+  # conditions go here by convention
+  
+  # rules go here by convention
+  
+  # helper methods go last
+end
+```
+
+### Conditions
+
+Conditions are facts about the state of the system.
+
+They have access to two elements of the proposition:
+
+- `@user` - the representation of a user in your system: the *subject* of the proposition.
+  `user` in `allowed?(user, ability, object)`. `@user` may be `nil`, which means
+  that the current user is anonymous (for example this may reflect an
+  unauthenticated request in your system).
+- `@subject` - any domain object that has an associated policy: the *object* of
+  the predicate of the proposition. `object` in `allowed?(user, ability, object)`.
+  `@subject` is never `nil`. See [handling `nil` values](./configuration.md#handling-nil-values)
+  for details of how to apply policies to `nil` values.
+  
+
+They are defined as `condition(name, **options, &block)`, where the block is
+evaluated in the context of an instance of the policy.
+
+For example:
+
+```ruby
+condition(:owns) { @subject.owner == @user }
+condition(:has_access_to) { @subject.owner.trusts?(@user) }
+condition(:old_enough_to_drive) { @user.age >= laws.minimum_age }
+condition(:has_driving_license) { @user.driving_license&.valid? }
+condition(:intoxicated, score: 5) { @user.blood_alcohol < laws.max_blood_alcohol }
+condition(:has_access_to, score: 3) { @subject.owner.trusts?(@user) }
+```
+
+These can be defined in any order, but we consider it best practice to define
+conditions at the top of the file.
+
+Conditions may call methods of the policy class, which can be helpful for
+memoizing some intermediate state:
+
+```ruby
+condition(:full_license) { license.full? }
+condition(:learner_license) { license.learner? }
+condition(:hgv_license) { license.heavy_goods? }
+
+def license
+  @license ||= Licenses.by_country(@user.country_of_residence).for_user(@user)
+end
+```
+
+Conditions are evaluated at most once, and their values are automatically
+memoized and cached (see [caching](./caching.md) for more detail).
+
+If you want to perform I/O (such as database access) or expensive computations,
+place this access in a condition.
+
+### Rules
+
+Rules are conclusions we can draw based on the facts:
+
+```ruby
+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
+```
+
+Rules are combined such that each ability must be enabled at least once, and not
+prevented in order to be permitted. So `enable` calls are implicitly combined
+with `ANY`, and `prevent` calls are implicitly combined with `ALL`.
+
+A set of conclusions can be defined for a single condition:
+
+```ruby
+rule { old_enough_to_drive }.policy do
+  enable :drive_vehicle
+  enable :vote
+end
+```
+
+Rule blocks do not have access to the internal state of the policy, and cannot
+access the `@user` or `@subject`, or any methods on the policy instance. You
+should not perform I/O in a rule. They exist solely to define the logical rules
+of implication and combination between conditions.
+
+### Complex conditions
+
+Conditions may be combined in the rule blocks:
+
+```ruby
+# A or B
+rule { owns | has_access_to }.enable :drive_vehicle
+# A and B
+rule { has_driving_license & old_enough_to_drive }.enable :drive_vehicle
+# Not A
+rule { ~has_driving_license }.prevent :drive_vehicle
+```
+
+And conditions can be implied from abilities:
+
+```ruby
+rule { can?(:drive_vehicle) }.enable :drive_taxi
+```
+
+### Delegation
+
+Policies may delegate to other policies. For example we could have a
+`DrivingLicense` class, and a `DrivingLicensePolicy`, which might contain rules
+like:
+
+```ruby
+class DrivingLicensePolicy < DeclarativePolicy::Base
+  condition(:expired) { @subject.expires_at <= Time.current }
+  
+  rule { expired }.prevent :drive_vehicle
+end
+```
+
+And a registration policy:
+
+```ruby
+class RegistrationPolicy < DeclarativePolicy::Base
+  condition(:valid) { @subject.valid_for?(@user.current_location) }
+  
+  rule { ~valid }.prevent :drive_vehicle
+end
+```
+
+Then in our `VehiclePolicy` we can delegate the license and registration
+checking to these two policies:
+
+```ruby
+delegate { @user.driving_license }
+delegate { @subject.registration }
+```
+
+This is a powerful mechanism for inferring rules based on relationships between
+objects.