graphql-armory 0.1.0.pre

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Integration
+        # Included in a field class by `include GraphQL::Armory::Authorization::Base`.
+        #
+        #   field :notes, String, authorize: :manage                      # another action on the parent
+        #   field :id, ID, authorize: :none, reason: "ids are public"     # declared bypass
+        #   field :owner_id, ID, authorize: true                          # the parent type's own action
+        #   field :notes, String, authorize: :manage, visible_when: :export  # hidden from users who cannot export
+        #
+        # A field with no rule is covered by its type's rule, unless the type is bypassed:
+        # coverage does not propagate from a bypass, so that field is denied.
+        #
+        # graphql-ruby hands `authorized?` the application object, not the type instance, so the type
+        # whose rule applies is the one that owns the field.
+        module Field
+          # `find_by: :id` looks the object up inside the user's scope instead of calling the resolver.
+          # `loads:` arguments also load through the scope unless `load_through_scope: false`.
+          def initialize(*args, authorize: nil, reason: nil, find_by: nil, load_through_scope: true, visible_when: nil, **kwargs, &block)
+            @armory_declared = authorize
+            @armory_reason = reason
+            @armory_visible_when = visible_when&.to_sym
+            @armory_load_through_scope = load_through_scope
+            Rule.none(reason: reason) if authorize == :none
+            super(*args, **kwargs, &block)
+            extension(Integration::FindBy, key: find_by) if find_by
+          end
+
+          attr_reader :armory_declared, :armory_reason, :armory_visible_when
+
+          def armory_load_through_scope?
+            @armory_load_through_scope
+          end
+
+          def object_from_id(type, id, context)
+            return super unless @armory_load_through_scope
+
+            Integration.find(type, nil, id, context)
+          end
+
+          # A `loads:` id that is not found is answered like a denial, so the client cannot tell the two apart.
+          def load_application_object_failed(error)
+            return super unless @armory_load_through_scope
+
+            raise GraphQL::UnauthorizedError.new(object: nil, type: error.argument.loads, context: error.context)
+          end
+
+
+          # `visible_when: :export` hides the field from users the owner's policy answers `false` for.
+          def visible?(context)
+            return super unless @armory_visible_when
+
+            unless owner.respond_to?(:armory_model)
+              raise ConfigurationError, "#{owner.graphql_name}.#{original_name} uses visible_when:, so its type must include Base"
+            end
+
+            rule = Rule.new(@armory_visible_when, attribute: original_name)
+            super && Integration.visible?(owner.armory_model, rule, context)
+          end
+
+          def authorized?(object, args, context)
+            rule = armory_rule_for(owner, context)
+            return false if rule.nil?
+
+            (rule == :covered || Integration.allowed?(object, rule, context)) && super
+          end
+
+          private
+
+          # A resolver or mutation that includes Base enforces its own rule, so the field is covered by it.
+          def armory_resolver?
+            resolver.respond_to?(:armory_rule)
+          end
+
+          # A Rule to check on the parent object, :covered when the type's own check already did it,
+          # or nil to deny.
+          def armory_rule_for(type, context)
+            type_rule = type.armory_rule if type.respond_to?(:armory_rule)
+
+            case @armory_declared
+            when nil
+              return :covered if armory_resolver?
+              return Integration.bypassed_implementer?(type, context.schema) ? nil : :covered if type.respond_to?(:kind) && type.kind.interface?
+              return :covered unless type.respond_to?(:armory_rule)
+
+              type_rule && (!type_rule.none? || type_rule.covers_fields?) ? :covered : nil
+            when true
+              type_rule unless type_rule&.none?
+            when :none
+              Rule.none(reason: @armory_reason)
+            else
+              Rule.new(@armory_declared, attribute: original_name)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Integration
+        # Field extension behind `field :invoice, Types::Invoice, find_by: :id`.
+        # It never calls the field's own resolver: the object is looked up inside the user's scope,
+        # so one the user may not see comes back exactly like one that does not exist.
+        class FindBy < GraphQL::Schema::FieldExtension
+          # The interpreter resolves one object at a time, Execution::Next a batch of them.
+          def resolve(arguments:, context:, object: nil, objects: nil)
+            key = options[:key]
+            found = Integration.find(field.type.unwrap, key, arguments[key], context)
+
+            objects ? Array.new(objects.size, found) : found
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Integration
+        # Extended onto an object type class by `include GraphQL::Armory::Authorization::Base`.
+        module Object
+          # `default_action :read` makes every type below be checked with `read` unless it declares its own.
+          def default_action(action = nil)
+            return @armory_default_action = action if action
+
+            @armory_default_action || (superclass.default_action if superclass.respond_to?(:default_action))
+          end
+
+          def authorize(action, reason: nil, **options)
+            @armory_rule = Rule.new(action, reason: reason, **options)
+          end
+
+          # Own rule, then an inherited one, then the default action. Nil means: nothing covers this type.
+          def armory_rule
+            return @armory_rule if @armory_rule
+
+            inherited = superclass.armory_rule if superclass.respond_to?(:armory_rule)
+            return inherited if inherited
+
+            action = default_action
+            Rule.new(action) if action
+          end
+
+          # The model the type wraps: `authorize :read, model: Invoice`, else the constant named like the type.
+          def armory_model
+            declared = armory_rule&.model
+            return declared if declared.is_a?(Class)
+
+            Object.const_get(declared || name&.split("::")&.last || graphql_name)
+          rescue NameError
+            raise ConfigurationError,
+                  "cannot tell which model #{graphql_name} wraps: declare it with `authorize :read, model: YourModel`"
+          end
+
+          # Runs before pagination, so connections page and count the scoped list.
+          def scope_items(items, context)
+            super(Integration.scoped(items, armory_rule, context), context)
+          end
+
+
+          # `authorize :read, visible_when: :export` hides the type from users the policy answers `false`
+          # for, in introspection and in error suggestions. Asked of the model's class, with no record.
+          def visible?(context)
+            rule = armory_rule
+            return super unless rule&.visible_when
+
+            super && Integration.visible?(armory_model, Rule.new(rule.visible_when, policy: rule.policy), context)
+          end
+
+          def authorized?(object, context)
+            rule = armory_rule
+            return false if rule.nil?
+
+            Integration.allowed?(object, rule, context) && super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Integration
+        # Class-level DSL of a resolver or mutation that includes `GraphQL::Armory::Authorization::Base`.
+        #
+        #   class ApproveInvoice < BaseMutation
+        #     authorize :approve, model: Invoice                  # InvoicePolicy#approve? on the loaded record
+        #     authorize :approve, model: Invoice, on_denied: :errors
+        #     authorize :none, reason: "anyone may call it"
+        #   end
+        #
+        # A mutation is an action, not a read: `default_action` does not apply, and one with no rule is denied.
+        module ResolverClass
+          ON_DENIED = %i[default errors].freeze
+
+          # `on_denied: :default` follows the schema's `on_unauthorized` mode, like a field. `:errors` answers
+          # `{ errors: [{ message: "Not allowed", code: "FORBIDDEN" }] }` as data: the payload needs an `errors` field.
+          def authorize(action, reason: nil, on_denied: :default, **options)
+            raise ArgumentError, "on_denied must be one of #{ON_DENIED.inspect}, got #{on_denied.inspect}" unless ON_DENIED.include?(on_denied)
+
+            @armory_on_denied = on_denied
+            @armory_rule = Rule.new(action, reason: reason, **options)
+          end
+
+          def armory_rule
+            @armory_rule || (superclass.armory_rule if superclass.respond_to?(:armory_rule))
+          end
+
+          def armory_on_denied
+            @armory_on_denied || (superclass.armory_on_denied if superclass.respond_to?(:armory_on_denied)) || :default
+          end
+
+          # The model the rule is asked about, which a mutation cannot be named after.
+          def armory_model
+            model = armory_rule&.model
+            return model if model.is_a?(Class)
+
+            raise ConfigurationError, "#{graphql_name}: declare the model with `authorize :action, model: YourModel`"
+          end
+        end
+
+        # Instance side: runs after the `loads:` arguments are loaded, so the policy sees the loaded record.
+        module Resolver
+          # Every loaded record of the model is asked about; with none loaded, the model's class is.
+          def authorized?(**inputs)
+            rule = self.class.armory_rule
+            return armory_denied if rule.nil?
+
+            allowed = armory_subjects(rule, inputs).all? { |subject| Integration.allowed?(subject, rule, context) }
+            allowed ? super : armory_denied
+          end
+
+          # `loads:` arguments are looked up inside the user's scope, so a foreign id answers like a missing one.
+          def object_from_id(type, id, context)
+            Integration.find(type, nil, id, context)
+          end
+
+          def load_application_object_failed(error)
+            raise GraphQL::UnauthorizedError.new(object: nil, type: error.argument.loads, context: error.context)
+          end
+
+          private
+
+          def armory_subjects(rule, inputs)
+            return [nil] if rule.none?
+
+            model = self.class.armory_model
+            loaded = inputs.values.flatten.select { |value| value.is_a?(model) }
+            loaded.empty? ? [model] : loaded
+          end
+
+          def armory_denied
+            return false unless self.class.armory_on_denied == :errors
+
+            [false, { errors: [{ message: "Not allowed", code: "FORBIDDEN" }] }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Integration
+        # Extended onto a schema class by `use GraphQL::Armory::Authorization`.
+        # Both engines route every denial through these hooks, so the client sees the same thing in each.
+        module Schema
+          def armory_configuration=(configuration)
+            @armory_configuration = configuration
+          end
+
+          def armory_configuration
+            @armory_configuration ||
+              (superclass.armory_configuration if superclass.respond_to?(:armory_configuration))
+          end
+
+          # `loads:` asks the schema which type an object is. For an object type the answer is known:
+          # the lookup went through that type's model. Abstract types and foreign objects are the app's call.
+          def resolve_type(type, object, context)
+            if !type.kind.abstract? && type.respond_to?(:armory_model) && object.is_a?(type.armory_model)
+              type
+            else
+              super
+            end
+          end
+
+          def unauthorized_object(error)
+            raise_denial(error)
+            nil
+          end
+
+          # A denied field that cannot be null must still fail: Execution::Next would otherwise leave
+          # a null in a non-null position without an error or a null propagation.
+          def unauthorized_field(error)
+            raise_denial(error)
+            raise_not_found if error.field&.type&.non_null?
+
+            nil
+          end
+
+          private
+
+          def raise_denial(error)
+            case armory_configuration.on_unauthorized
+            when :error then raise_not_found
+            when :raise then raise NotAuthorizedError, error.type&.graphql_name
+            end
+          end
+
+          # The same answer a missing object gets, so a denial does not reveal that it exists.
+          def raise_not_found
+            raise GraphQL::ExecutionError.new("Not found", extensions: { "code" => "NOT_FOUND" })
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "graphql/armory/authorization/integration/schema"
+require "graphql/armory/authorization/integration/object"
+require "graphql/armory/authorization/integration/find_by"
+require "graphql/armory/authorization/integration/field"
+require "graphql/armory/authorization/integration/argument"
+require "graphql/armory/authorization/integration/resolver"
+require "graphql/armory/authorization/integration/base"
+
+module GraphQL
+  module Armory
+    module Authorization
+      # Translates graphql-ruby's hooks into questions for the core. No permission logic lives here.
+      module Integration
+        # In graphql 2.5.26 to 2.6.1 Execution::Next resolves a denied field against a nil object and crashes.
+        NEXT_MINIMUM = Gem::Version.new("2.6.2")
+        NEXT_SUPPORTED = Gem::Version.new(GraphQL::VERSION) >= NEXT_MINIMUM
+
+        def self.configuration(context)
+          check_engine!(context)
+
+          schema = context.schema
+          return schema.armory_configuration if schema.respond_to?(:armory_configuration)
+
+          raise ConfigurationError,
+                "this schema never installed the plugin: add `use GraphQL::Armory::Authorization, adapter: ...` to #{schema}"
+        end
+
+        def self.check_engine!(context, supported: NEXT_SUPPORTED)
+          return if supported || !context[:__graphql_execute_next]
+
+          raise ConfigurationError,
+                "Execution::Next needs graphql >= #{NEXT_MINIMUM} (running #{GraphQL::VERSION}): " \
+                "a denied field crashes it in earlier versions"
+        end
+
+        # Narrows a list to what the user may see. Without a rule nothing is visible.
+        def self.scoped(items, rule, context)
+          return Adapters::Null.new.scope(nil, items, rule) if rule.nil?
+
+          configuration = configuration(context)
+          Scope.(items, rule, context, adapter: configuration.adapter, sinks: configuration.sinks)
+        end
+
+        # Looks an object up inside the user's scope, by primary key unless a key is given.
+        # What is out of scope and what does not exist look the same: nil.
+        def self.find(type, key, value, context)
+          unless type.respond_to?(:armory_model)
+            raise ConfigurationError,
+                  "#{type.graphql_name} cannot be looked up through a scope: " \
+                  "include GraphQL::Armory::Authorization::Base in its base class"
+          end
+
+          model = type.armory_model
+          rule = type.armory_rule
+          conditions = { (key || model.primary_key) => value }
+          return scoped(model.all, rule, context).find_by(conditions) unless rule&.scope == :in_memory
+
+          # An in-memory scope yields an Array, which cannot look one record up: find it, then ask the rule.
+          record = model.find_by(conditions)
+          record if record && allowed?(record, rule, context)
+        end
+
+        # An interface field with no rule of its own cannot name the type it is resolved on, so it is only
+        # covered when no implementer is a bypass: a field on a bypassed type is denied, and so is this one.
+        def self.bypassed_implementer?(interface, schema)
+          schema.possible_types(interface).any? do |type|
+            rule = type.armory_rule if type.respond_to?(:armory_rule)
+            rule && rule.none? && !rule.covers_fields?
+          end
+        end
+
+        # One Authorize per query: building it (and its memo and telemetry) once per object is pure overhead.
+        def self.allowed?(subject, rule, context)
+          store = context.namespace(:armory)
+          authorize = store[:authorize] ||= begin
+            configuration = configuration(context)
+            Authorize.build(context, adapter: configuration.adapter, sinks: configuration.sinks)
+          end
+
+          authorize.(subject, rule, context)
+        end
+
+        # Whether a type or field may appear in the schema this user sees. The question is asked of the
+        # model's class, with no record, so the rule's action must be one a policy can answer that way.
+        # `Schema.types` with no context sees the whole schema. A schema dump asks for it explicitly with
+        # `to_definition(context: { armory_full_schema: true })`: graphql 2.6 builds an ordinary context for it,
+        # which cannot be told from an anonymous request, and an anonymous request must not see hidden members.
+        def self.visible?(model, rule, context)
+          unless context.respond_to?(:namespace)
+            raise ConfigurationError,
+                  "visible_when: needs a per-query context; static Schema::Visibility profiles are not supported, " \
+                  "use `dynamic: true` or no profiles"
+          end
+
+          return true if context.is_a?(GraphQL::Query::NullContext) || context[:armory_full_schema] == true
+
+          allowed?(model, rule, context)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      # Remembers answers for the length of a request, so the same question is not asked twice.
+      class Memo
+        def self.build(context)
+          store = context.namespace(:armory)
+          store[:memo] ||= new
+        end
+
+        def initialize
+          # Keyed by identity: two equal-looking records are different subjects, and holding the
+          # subject as a key keeps it alive, so an object id can never be recycled for another one.
+          @answers = {}.compare_by_identity
+        end
+
+        def fetch(subject, rule)
+          answers = (@answers[subject] ||= {})
+          return answers[rule] if answers.key?(rule)
+
+          answers[rule] = yield
+        end
+
+        # Never remembers: every question runs.
+        class Substitute
+          def fetch(_subject, _rule)
+            yield
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# `require "graphql/armory/authorization/rspec"` in your spec helper, then:
+#
+#   expect(AppSchema).to be_fully_authorized
+RSpec::Matchers.define :be_fully_authorized do
+  match do |schema|
+    @report = GraphQL::Armory::Authorization::Audit.(schema)
+    @report.ok?
+  end
+
+  failure_message do |schema|
+    "expected #{schema} to be fully authorized, but the audit found:\n#{@report}"
+  end
+
+  failure_message_when_negated do |schema|
+    "expected #{schema} not to be fully authorized, but the audit found no problems"
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      # Immutable value holding what was declared, e.g. `authorize :read`.
+      # Each adapter reads the parts it needs (policy, subject, attribute, model, scope).
+      class Rule
+        attr_reader :action, :policy, :subject, :attribute, :model, :scope, :visible_when, :covers_fields, :reason
+
+        def self.none(reason:)
+          new(:none, reason: reason)
+        end
+
+        def initialize(action, policy: nil, subject: nil, attribute: nil, model: nil, scope: nil, visible_when: nil, covers_fields: false, reason: nil)
+          raise ArgumentError, "a rule needs an action" if action.nil?
+
+          @action = action.to_sym
+          @policy = policy
+          @subject = subject
+          @attribute = attribute
+          @model = model
+          @scope = scope
+          @visible_when = visible_when&.to_sym
+          @covers_fields = covers_fields
+          @reason = reason
+
+          raise ArgumentError, "a bypass needs a reason" if none? && reason.to_s.strip.empty?
+
+          raise ArgumentError, "covers_fields only applies to a bypass (`authorize :none`)" if covers_fields && !none?
+
+          freeze
+        end
+
+        # A bypassed type whose fields are covered by something else, such as the payload of a mutation.
+        def covers_fields?
+          covers_fields
+        end
+
+        def none?
+          action == :none
+        end
+
+        def ==(other)
+          other.is_a?(Rule) && members == other.members
+        end
+        alias eql? ==
+
+        def hash
+          members.hash
+        end
+
+        protected
+
+        def members
+          [action, policy, subject, attribute, model, scope, visible_when, covers_fields, reason]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      # Narrows a list to what the actor may see. A declared bypass leaves the list alone.
+      class Scope
+        attr_reader :adapter, :telemetry
+
+        # `new` is inert: with no configuration every list is scoped down to nothing.
+        def initialize(adapter: Adapters::Null.new, telemetry: Telemetry.new)
+          @adapter = adapter
+          @telemetry = telemetry
+        end
+
+        def self.build(adapter:, sinks: [])
+          new(adapter: adapter, telemetry: Telemetry.build(sinks: sinks))
+        end
+
+        def self.call(items, rule, context, adapter:, sinks: [])
+          build(adapter: adapter, sinks: sinks).(items, rule, context)
+        end
+
+        def call(items, rule, context)
+          if rule.none?
+            telemetry.record(:bypassed, reason: rule.reason)
+            return items
+          end
+
+          scoped = adapter.scope(adapter.actor(context), items, rule)
+          telemetry.record(:scoped, action: rule.action)
+          scoped
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      # Records what happened (allowed, denied, bypassed, scoped) and hands it to its sinks.
+      # A sink is anything that responds to `call(signal, data)`. Never put record attributes in `data`.
+      class Telemetry
+        def self.build(sinks: [])
+          new(sinks: sinks)
+        end
+
+        def initialize(sinks: [])
+          @sinks = sinks
+        end
+
+        def record(signal, **data)
+          @sinks.each { |sink| sink.call(signal, data) }
+          nil
+        end
+
+        # Keeps what was recorded, for tests.
+        class Substitute
+          attr_reader :recorded
+
+          def initialize
+            @recorded = []
+          end
+
+          def record(signal, **data)
+            @recorded << [signal, data]
+            nil
+          end
+
+          def recorded?(signal)
+            @recorded.any? { |recorded_signal, _| recorded_signal == signal }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "graphql/armory/authorization/errors"
+require "graphql/armory/authorization/configuration"
+require "graphql/armory/authorization/rule"
+require "graphql/armory/authorization/memo"
+require "graphql/armory/authorization/telemetry"
+require "graphql/armory/authorization/adapters/null"
+require "graphql/armory/authorization/adapters/substitute"
+require "graphql/armory/authorization/authorize"
+require "graphql/armory/authorization/scope"
+require "graphql/armory/authorization/audit"
+require "graphql/armory/authorization/controls/rule"
+require "graphql/armory/authorization/controls/context"
+require "graphql/armory/authorization/controls/actor"
+require "graphql/armory/authorization/controls/subject"
+require "graphql/armory/authorization/integration"
+
+module GraphQL
+  module Armory
+    module Authorization
+      module Adapters
+        # Loaded on first use, so only the library behind the adapter you pick is required.
+        autoload :Pundit, "graphql/armory/authorization/adapters/pundit"
+        autoload :CanCan, "graphql/armory/authorization/adapters/cancan"
+      end
+    end
+
+    # Deny-by-default authorization. The core (Authorize, Scope) knows nothing about
+    # Pundit or CanCanCan: it asks an adapter four questions and trusts only a clear answer.
+    module Authorization
+      # The schema plugin: `use GraphQL::Armory::Authorization, adapter: :pundit`.
+      # Options: `adapter:` (:pundit or an adapter object), `on_unauthorized:` (:null, :error or :raise),
+      # `sinks:` (callables that receive each telemetry signal).
+      def self.use(schema_defn, **options)
+        schema_defn.extend(Integration::Schema)
+        schema_defn.armory_configuration = Configuration.new(**options)
+      end
+    end
+  end
+end