graphql-armory 0.1.0.pre

data/lib/graphql/armory/authorization/adapters/substitute.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Adapters
+        # An adapter with canned answers that keeps the questions it was asked, for tests.
+        class Substitute
+          attr_reader :asked, :scoped_for
+
+          def initialize(allow: true, actor: nil, scoped: :itself.to_proc, raises: nil, raises_on_scope: nil)
+            @allow = allow
+            @actor = actor
+            @scoped = scoped
+            @raises = raises
+            @raises_on_scope = raises_on_scope
+            @asked = []
+            @scoped_for = []
+          end
+
+          def actor(_context)
+            @actor
+          end
+
+          def authorized?(actor, subject, rule)
+            raise @raises if @raises
+
+            @asked << [actor, subject, rule]
+            @allow
+          end
+
+          def scope(actor, items, rule)
+            raise @raises_on_scope if @raises_on_scope
+
+            @scoped_for << [actor, items, rule]
+            @scoped.call(items)
+          end
+
+          def check(_type, _rule)
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/audit/command.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Audit
+        # What `rake graphql_armory:audit[YourSchema]` runs: prints the report and answers an exit status.
+        class Command
+          def initialize(out: $stdout)
+            @out = out
+          end
+
+          def call(schema_name)
+            return fail_with("Name the schema: rake graphql_armory:audit[YourSchema]") if schema_name.to_s.empty?
+
+            schema = Object.const_get(schema_name)
+            report = Audit.(schema)
+            @out.print(report)
+            report.ok? ? 0 : 1
+          rescue NameError => error
+            raise unless error.name.to_s == schema_name.to_s.split("::").last
+
+            fail_with("No schema named #{schema_name}")
+          end
+
+          private
+
+          def fail_with(message)
+            @out.puts(message)
+            1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/audit/report.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Audit
+        # What an audit found: what is not covered, and every bypass someone declared.
+        class Report
+          Problem = Struct.new(:kind, :path, :message) do
+            def to_s
+              "#{path} (#{kind}): #{message}"
+            end
+          end
+
+          Bypass = Struct.new(:path, :reason)
+
+          attr_reader :problems, :bypasses
+
+          def initialize(problems:, bypasses:)
+            @problems = problems.freeze
+            @bypasses = bypasses.freeze
+            freeze
+          end
+
+          def ok?
+            problems.empty?
+          end
+
+          def to_s
+            [problems_text, bypasses_text].compact.join("\n\n") << "\n"
+          end
+
+          private
+
+          def problems_text
+            return "No problems." if ok?
+
+            ["#{problems.size} #{problems.size == 1 ? 'problem' : 'problems'}:", *problems.map { |problem| "  #{problem}" }].join("\n")
+          end
+
+          def bypasses_text
+            return if bypasses.empty?
+
+            ["#{bypasses.size} declared #{bypasses.size == 1 ? 'bypass' : 'bypasses'}:",
+             *bypasses.map { |bypass| "  #{bypass.path}: #{bypass.reason}" }].join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/audit.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "set"
+require "graphql/armory/authorization/audit/report"
+require "graphql/armory/authorization/audit/command"
+
+module GraphQL
+  module Armory
+    module Authorization
+      # Walks a schema, without running a query, and reports everything that is not covered:
+      # types nobody protected, types without a rule or a policy, fields with no rule on a bypassed
+      # type, and `loads:` that skip the scope. Every declared bypass is listed with its reason.
+      class Audit
+        RELAY_TYPES = [GraphQL::Types::Relay::BaseConnection, GraphQL::Types::Relay::BaseEdge,
+                       GraphQL::Types::Relay::PageInfo].freeze
+
+        attr_reader :adapter
+
+        # `new` is inert: with no adapter nothing can be verified, so nothing is covered.
+        def initialize(adapter: Adapters::Null.new)
+          @adapter = adapter
+        end
+
+        def self.build(schema)
+          configuration = schema.armory_configuration if schema.respond_to?(:armory_configuration)
+          configuration ? new(adapter: configuration.adapter) : new
+        end
+
+        def self.call(schema)
+          build(schema).(schema)
+        end
+
+        def call(schema)
+          findings = Findings.new
+          unless schema.respond_to?(:armory_configuration) && schema.armory_configuration
+            findings.problem(:plugin, "Schema", "never installed the plugin: add `use GraphQL::Armory::Authorization, adapter: ...`")
+          end
+
+          audited_types(schema).each { |type| audit_type(type, findings) }
+          schema.types.each_value { |type| audit_interface(type, schema, findings) if type.kind.interface? && !type.introspection? }
+          findings.report
+        end
+
+        private
+
+        # Walks `schema.types`, which a schema that hides types with `visible?` would filter.
+        def audited_types(schema)
+          schema.types.values.select do |type|
+            type.kind.object? && !type.introspection? && RELAY_TYPES.none? { |relay| type <= relay }
+          end
+        end
+
+        def audit_type(type, findings)
+          path = type.graphql_name
+          unless type.respond_to?(:armory_rule)
+            findings.problem(:unprotected, path, "its base class does not include GraphQL::Armory::Authorization::Base, so it is open")
+            return
+          end
+
+          rule = type.armory_rule
+          if rule.nil?
+            findings.problem(:no_rule, path, "has no rule and no default_action, so it is denied")
+          elsif rule.none?
+            findings.bypass(path, rule.reason)
+            audit_fields(type, findings, model: nil, bypassed: !rule.covers_fields?, reported: Set.new)
+          else
+            model = model_of(type, path, findings)
+            reported = Set.new
+            check(path, model, rule, findings, reported) if model
+            check(path, model, Rule.new(rule.visible_when, policy: rule.policy), findings, reported) if model && rule.visible_when
+            audit_fields(type, findings, model: model, bypassed: false, reported: reported)
+          end
+        end
+
+        # An interface field with no rule is denied when any implementer is a bypass; the fix is to declare it.
+        def audit_interface(interface, schema, findings)
+          return unless Integration.bypassed_implementer?(interface, schema)
+
+          interface.fields.each_value do |field|
+            next unless field.respond_to?(:armory_declared) && field.armory_declared.nil?
+
+            findings.problem(:field_without_rule, "#{interface.graphql_name}.#{field.original_name}",
+                             "declares no rule and an implementing type is bypassed, so it is denied")
+          end
+        end
+
+        def model_of(type, path, findings)
+          type.armory_model
+        rescue ConfigurationError => error
+          findings.problem(:model, path, error.message)
+          nil
+        end
+
+        # An adapter problem shows once per type, however many fields declare an action of their own.
+        def check(path, model, rule, findings, reported)
+          adapter.check(model, rule).each do |message|
+            findings.problem(:adapter, path, message) if reported.add?(message)
+          end
+        end
+
+        def audit_fields(type, findings, model:, bypassed:, reported:)
+          type.all_field_definitions.each do |field|
+            path = "#{type.graphql_name}.#{field.original_name}"
+            next findings.problem(:field_without_rule, path, "its field class does not include Base, so it is denied") if bypassed && !field.respond_to?(:armory_declared)
+            next unless field.respond_to?(:armory_declared)
+            next audit_resolver(field, path, findings) if field.resolver.respond_to?(:armory_rule)
+
+            audit_declaration(field, path, findings, model: model, bypassed: bypassed, reported: reported)
+            audit_visibility(field, path, findings, model: model, reported: reported)
+            audit_loads(field, path, findings)
+            audit_arguments(field, path, findings, reported: reported)
+          end
+        end
+
+        # A resolver or mutation carries its own rule: no rule is denied, `:none` is listed, an action is checked.
+        def audit_resolver(field, path, findings)
+          resolver = field.resolver
+          rule = resolver.armory_rule
+          return findings.problem(:no_rule, path, "its mutation or resolver declares no `authorize`, so it is denied") if rule.nil?
+          return findings.bypass(path, rule.reason) if rule.none?
+
+          model = begin
+            resolver.armory_model
+          rescue ConfigurationError => error
+            return findings.problem(:model, path, error.message)
+          end
+          check(path, model, rule, findings, Set.new)
+        end
+
+        # The action a field is hidden with is asked of the policy like any other, so it must exist.
+        def audit_visibility(field, path, findings, model:, reported:)
+          return unless model && field.armory_visible_when
+
+          check(path.split(".").first, model, Rule.new(field.armory_visible_when, attribute: field.original_name), findings, reported)
+        end
+
+        def audit_declaration(field, path, findings, model:, bypassed:, reported:)
+          case (declared = field.armory_declared)
+          when :none
+            findings.bypass(path, field.armory_reason)
+          when nil, true
+            if bypassed
+              findings.problem(:field_without_rule, path, "declares no rule and its type is bypassed, so it is denied")
+            end
+          else
+            check(path.split(".").first, model, Rule.new(declared), findings, reported) if model
+          end
+        end
+
+        # An argument that declares a rule is listed (a bypass with its reason) or checked like a field's action.
+        def audit_arguments(field, path, findings, reported:)
+          field.all_argument_definitions.each do |argument|
+            next unless argument.respond_to?(:armory_declared)
+
+            apath = "#{path}(#{argument.keyword})"
+            declared = argument.armory_declared
+            findings.bypass(apath, argument.armory_reason) if declared == :none
+            [declared, argument.armory_visible_when].compact.reject { |action| action == :none }.each do |action|
+              audit_argument_action(argument, apath, action, findings, reported)
+            end
+          end
+        end
+
+        def audit_argument_action(argument, path, action, findings, reported)
+          check(path.split(".").first, argument.armory_model, Rule.new(action, attribute: argument.keyword), findings, reported)
+        rescue ConfigurationError => error
+          findings.problem(:model, path, error.message)
+        end
+
+        def audit_loads(field, path, findings)
+          return if field.armory_load_through_scope?
+
+          field.all_argument_definitions.select(&:loads).each do |argument|
+            name = GraphQL::Schema::Member::BuildType.underscore(argument.graphql_name)
+            findings.problem(:unscoped_load, "#{path}(#{name})", "loads through the app's object_from_id, not through the user's scope")
+          end
+        end
+
+        # Collects what one audit finds.
+        class Findings
+          def initialize
+            @problems = []
+            @bypasses = []
+          end
+
+          def problem(kind, path, message)
+            @problems << Report::Problem.new(kind, path, message)
+          end
+
+          def bypass(path, reason)
+            @bypasses << Report::Bypass.new(path, reason)
+          end
+
+          def report
+            Report.new(problems: @problems.sort_by { |problem| [problem.path, problem.kind.to_s] },
+                       bypasses: @bypasses.sort_by(&:path))
+          end
+        end
+
+        # Answers the report it was given, for tests.
+        class Substitute
+          def initialize(report)
+            @report = report
+          end
+
+          def call(_schema)
+            @report
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/authorize.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      # Can this actor perform this rule's action on this subject? Anything but a clear `true` is a denial.
+      class Authorize
+        attr_reader :adapter, :memo, :telemetry
+
+        # `new` is inert: with no configuration it denies everything.
+        def initialize(adapter: Adapters::Null.new, memo: Memo.new, telemetry: Telemetry.new)
+          @adapter = adapter
+          @memo = memo
+          @telemetry = telemetry
+        end
+
+        def self.build(context, adapter:, sinks: [])
+          new(adapter: adapter, memo: Memo.build(context), telemetry: Telemetry.build(sinks: sinks))
+        end
+
+        def self.call(subject, rule, context, adapter:, sinks: [])
+          build(context, adapter: adapter, sinks: sinks).(subject, rule, context)
+        end
+
+        def call(subject, rule, context)
+          return bypass(subject, rule) if rule.none?
+
+          memo.fetch(subject, rule) { decide(subject, rule, context) }
+        end
+
+        private
+
+        def bypass(subject, rule)
+          telemetry.record(:bypassed, type: subject.class.name, reason: rule.reason)
+          true
+        end
+
+        def decide(subject, rule, context)
+          answer = adapter.authorized?(adapter.actor(context), subject, rule)
+
+          case answer
+          when true, false, nil
+            allowed = answer == true
+            telemetry.record(allowed ? :allowed : :denied, type: subject.class.name, action: rule.action)
+            allowed
+          else
+            raise AdapterError, "#{adapter.class} answered #{answer.inspect}; it must answer true, false or nil"
+          end
+        end
+
+        # Answers what it was told and keeps the calls, for tests.
+        class Substitute
+          attr_reader :calls
+
+          def initialize(answer: true)
+            @answer = answer
+            @calls = []
+          end
+
+          def call(subject, rule, _context)
+            @calls << [subject, rule]
+            @answer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      # What `use GraphQL::Armory::Authorization, ...` stores on the schema.
+      class Configuration
+        MODES = %i[null error raise].freeze
+
+        attr_reader :adapter, :on_unauthorized, :sinks
+
+        def initialize(adapter:, on_unauthorized: :null, sinks: [])
+          unless MODES.include?(on_unauthorized)
+            raise ArgumentError, "on_unauthorized must be one of #{MODES.inspect}, got #{on_unauthorized.inspect}"
+          end
+
+          @adapter = resolve(adapter)
+          @on_unauthorized = on_unauthorized
+          @sinks = sinks
+        end
+
+        private
+
+        def resolve(adapter)
+          case adapter
+          when :pundit then Adapters::Pundit.new
+          when :cancan then Adapters::CanCan.new
+          when Symbol, String then raise ArgumentError, "unknown adapter #{adapter.inspect}; use :pundit, :cancan or an adapter object"
+          else adapter
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/controls/actor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Controls
+        Actor = Struct.new(:id) do
+          def self.example(id: 1)
+            new(id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/controls/context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Controls
+        # Stands in for GraphQL::Query::Context: values plus a namespace per library.
+        class Context
+          def self.example(**values)
+            new(values)
+          end
+
+          def initialize(values)
+            @values = values
+            @namespaces = Hash.new { |namespaces, name| namespaces[name] = {} }
+          end
+
+          def [](key)
+            @values[key]
+          end
+
+          def namespace(name)
+            @namespaces[name]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/controls/rule.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Controls
+        module Rule
+          def self.example(action: :read, **options)
+            Authorization::Rule.new(action, **options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/controls/subject.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Controls
+        Subject = Struct.new(:id) do
+          def self.example(id: 1)
+            new(id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Error < Armory::Error; end
+
+      # An adapter answered something other than true, false or nil.
+      class AdapterError < Error; end
+
+      # An adapter cannot narrow a list to what the actor may see.
+      class MissingScopeError < Error; end
+
+      # The schema or a class was not set up the way the integration needs.
+      class ConfigurationError < Error; end
+
+      # Raised on a denial when the schema asks for `on_unauthorized: :raise`.
+      # It names the type but never the record.
+      class NotAuthorizedError < Error
+        attr_reader :type_name
+
+        def initialize(type_name = nil)
+          @type_name = type_name
+          super("Not authorized to access #{type_name || 'this object'}")
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/integration/argument.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Integration
+        # Included in an argument class by `include GraphQL::Armory::Authorization::Base`.
+        #
+        #   argument :include_internal, Boolean, authorize: :manage            # checked when the client sends it
+        #   argument :tag, String, visible_when: :export                       # hidden from users who cannot export
+        #   argument :status, String, authorize: :none, reason: "public"      # declared, listed in the audit
+        #
+        # An argument with no rule is covered by its field: the field already decides whether the user may call it.
+        # A declared rule is checked on top, only when the client sends the argument (graphql-ruby skips
+        # arguments left at their default), and a denial denies the whole field.
+        #
+        # The question is asked of the parent object when it is an instance of the model, else of the model's
+        # class (a root field has no record). The model is the one the field's type wraps, or `model:`.
+        module Argument
+          def initialize(*args, authorize: nil, reason: nil, model: nil, visible_when: nil, **kwargs, &block)
+            unless [nil, :none].include?(authorize) || authorize.is_a?(Symbol)
+              raise ArgumentError, "an argument's `authorize:` is an action or :none, not #{authorize.inspect}"
+            end
+
+            if authorize && authorize != :none && kwargs.key?(:default_value)
+              raise ArgumentError,
+                    "a restricted argument cannot have a default_value: the interpreter skips the check for a default " \
+                    "and Execution::Next applies it, so the engines would disagree"
+            end
+
+            @armory_declared = authorize
+            @armory_reason = reason
+            @armory_model = model
+            @armory_visible_when = visible_when&.to_sym
+            Rule.none(reason: reason) if authorize == :none
+            super(*args, **kwargs, &block)
+          end
+
+          attr_reader :armory_declared, :armory_reason, :armory_visible_when
+
+          def armory_model
+            @armory_model || armory_field_model
+          end
+
+          def authorized?(object, value, context)
+            return super if @armory_declared.nil? || @armory_declared == :none
+
+            model = armory_model
+            subject = object.is_a?(model) ? object : model
+            Integration.allowed?(subject, Rule.new(@armory_declared, attribute: keyword), context) && super
+          end
+
+          def visible?(context)
+            return super unless @armory_visible_when
+
+            super && Integration.visible?(armory_model, Rule.new(@armory_visible_when, attribute: keyword), context)
+          end
+
+          private
+
+          def armory_field_model
+            type = owner.respond_to?(:owner) ? owner.owner : owner
+            model = type.armory_model if type.respond_to?(:armory_model)
+            return model if model
+
+            raise ConfigurationError, "#{keyword}: cannot tell which model to ask about, pass `model: YourModel`"
+          rescue ConfigurationError
+            raise ConfigurationError, "#{keyword}: cannot tell which model to ask about, pass `model: YourModel`"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/integration/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      # One module for every base class. It detects what it was included in.
+      #
+      #   class Types::BaseObject < GraphQL::Schema::Object
+      #     include GraphQL::Armory::Authorization::Base
+      #     default_action :read
+      #   end
+      #   class Types::BaseField < GraphQL::Schema::Field
+      #     include GraphQL::Armory::Authorization::Base
+      #   end
+      module Base
+        def self.included(base)
+          if base <= GraphQL::Schema::Object
+            base.extend(Integration::Object)
+          elsif base <= GraphQL::Schema::Field
+            base.include(Integration::Field)
+          elsif base <= GraphQL::Schema::Resolver
+            base.extend(Integration::ResolverClass)
+            base.include(Integration::Resolver)
+          elsif base <= GraphQL::Schema::Argument
+            base.include(Integration::Argument)
+          else
+            raise ArgumentError,
+                  "GraphQL::Armory::Authorization::Base can only be included in a GraphQL object, field, argument, resolver or mutation class, not #{base}. Interfaces and unions are not authorized themselves: declare the rule on their possible types"
+          end
+        end
+      end
+    end
+  end
+end