graphql-armory 0.1.0.pre8 → 0.1.0.pre9

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Audit
+        # A rule under `observe:` serves what it would refuse, so it is a problem until someone enforces it.
+        class ObservedRules
+          def self.call(schema, definitions, findings)
+            definitions.each do |type|
+              rule = type.armory_rule if type.respond_to?(:armory_rule)
+              report(findings, type.graphql_name, rule.observe, unobservable(type)) if rule&.observed?
+              next unless type.respond_to?(:fields)
+
+              Definitions.fields_at_every_level(type).each do |field|
+                reason = observed_reason(field)
+                report(findings, "#{type.graphql_name}.#{field.graphql_name}", reason, field.resolver ? field : nil) if reason
+              end
+            end
+            custom_introspection(schema).each { |field| report(findings, "#{field.owner.graphql_name}.#{field.graphql_name}", field.armory_observe) }
+          end
+
+          def self.report(findings, path, reason, resolver_field = nil)
+            effect = if resolver_field
+                       "raises on every query, because #{resolver_field.graphql_name} has a resolver or a mutation, which can write (#{reason}): remove observe:"
+                     else
+                       "serves what this rule would refuse (#{reason}): remove it to enforce the rule"
+                     end
+            findings.problem(:observed, path, "observe: #{effect}")
+          end
+
+          # Its own observe:, or `authorize: true` on an owner whose rule is observed: if that owner is only a parent, no
+          # type reports its rule.
+          def self.observed_reason(field)
+            return field.armory_observe if field.respond_to?(:armory_observe) && field.armory_observe
+            return unless field.respond_to?(:armory_declared) && field.armory_declared == true
+
+            rule = field.owner.armory_rule if field.owner.respond_to?(:armory_rule)
+            rule.observe if rule&.observed?
+          end
+
+          def self.unobservable(type)
+            type.all_field_definitions.find(&:resolver)
+          end
+          private_class_method :observed_reason, :unobservable
+
+          # Definitions holds what these fields return, not the classes that own them.
+          def self.custom_introspection(schema)
+            system = schema.introspection_system
+            (system.entry_points + system.dynamic_fields).select { |field| field.respond_to?(:armory_observe) && field.armory_observe }
+          end
+          private_class_method :custom_introspection
+          private_class_method :report
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Audit
+        # A payload's fields are covered by the mutation's rule, so they check nothing themselves. A field that returns the
+        # payload without being a mutation with a rule serves them with none run: a user the mutation refuses gets the data.
+        # It reads the definitions and not the schema's lookups, which filter by visibility and may need a profile.
+        class PayloadReuse
+          def self.call(definitions, findings)
+            new(findings).(definitions)
+          end
+
+          def initialize(findings = Findings.new)
+            @findings = findings
+          end
+
+          def call(definitions)
+            objects = definitions.select { |type| type.kind.object? }
+            fields = objects.flat_map { |type| Definitions.fields_at_every_level(type).map { |field| [type, field] } }
+            guarded = fields.filter_map { |_type, field| field.resolver.payload_type if ruled_resolver?(field.resolver) }.uniq
+            payloads = objects.select do |type|
+              next false if own_rule?(type)
+
+              guarded.any? { |payload| type <= payload } || generated_by_ruled_mutation?(type) || holds_field_of_ruled_mutation?(type)
+            end
+            return if payloads.empty?
+
+            named = definitions.to_h { |type| [type.graphql_name, type] }
+            fields.each { |type, field| note(type, field, objects, payloads, named) }
+          end
+
+          private
+
+          # graphql-ruby marks the payload it generates with its mutation, which the schema may not hold at all.
+          def generated_by_ruled_mutation?(type)
+            type.ancestors.any? { |ancestor| ancestor.respond_to?(:mutation) && ruled_resolver?(ancestor.mutation) }
+          end
+
+          # A field keeps the mutation that defined it as its owner, wherever it ends up.
+          def holds_field_of_ruled_mutation?(type)
+            Definitions.fields_at_every_level(type).any? do |field|
+              field.respond_to?(:armory_declared) && field.armory_declared.nil? && ruled_resolver?(field.owner)
+            end
+          end
+
+          def ruled_resolver?(resolver)
+            return false unless resolver.respond_to?(:payload_type) && resolver.respond_to?(:armory_rule)
+
+            rule = resolver.armory_rule
+            !rule.nil? && !rule.none?
+          end
+
+          # A type with a rule of its own checks itself wherever it is returned: `payload_type Types::Invoice`.
+          def own_rule?(type)
+            return false unless type.respond_to?(:armory_rule)
+
+            rule = type.armory_rule
+            !rule.nil? && !rule.none?
+          end
+
+          def note(type, field, objects, payloads, named)
+            target = returned_type(field, named) or return
+            reused = members(target, objects) & payloads
+            return if reused.empty? || own_payload?(field, target)
+
+            @findings.problem(:payload_outside_mutation, "#{type.graphql_name}.#{field.original_name}",
+                              "returns #{reused.map(&:graphql_name).sort.join(", ")}, a mutation's payload, whose fields are covered by that mutation's rule: " \
+                              "here no such rule runs, so they are served with no check. Return a type of its own, or, for a public child of a mutation with a rule, give the parent's field `authorize: :none, reason: \"...\"`")
+          end
+
+          # A shadowed definition may name a type that never resolved; it cannot serve anything.
+          def returned_type(field, named)
+            type = field.type.unwrap
+            type.is_a?(GraphQL::Schema::LateBoundType) ? named[type.graphql_name] : type
+          rescue NameError, GraphQL::Error
+            nil
+          end
+
+          def members(target, objects)
+            return target.all_possible_types if target.kind.union?
+            return objects.select { |type| type <= target } if target.kind.interface?
+
+            [target]
+          end
+
+          def own_payload?(field, target)
+            ruled_resolver?(field.resolver) && field.resolver.payload_type == target
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Audit
+        # A type's covers_fields says a rule runs elsewhere, and on a resolver or mutation with no Base none does: it runs
+        # with no check. A plain method under the same type is the declaration's own meaning, and it is listed by the type.
+        module PlainResolvers
+          PROBLEM = "its resolver or mutation does not include GraphQL::Armory::Authorization::Base, so no rule of this gem runs on it and the type's covers_fields serves it, unless its own code refuses. " \
+                    "Include Base and declare `authorize`, or declare `authorize: :none, reason: \"...\"` on the field"
+          PLAIN_FIELD_PROBLEM = "its resolver or mutation does not include GraphQL::Armory::Authorization::Base and neither does its field class, so no rule of this gem runs on it and the type's covers_fields " \
+                                "serves it, unless its own code refuses. Include Base in the resolver and declare `authorize`, or use a field class that includes Base and declare `authorize: :none, reason: \"...\"`"
+
+          def self.report(findings, path, field)
+            findings.problem(:unprotected, path, field.respond_to?(:armory_declared) ? PROBLEM : PLAIN_FIELD_PROBLEM)
+          end
+
+          def self.covering?(rule)
+            !rule.nil? && rule.none? && rule.covers_fields?
+          end
+
+          # A field that names its own rule, or that its parent mutation's rule already answered, does not depend on covers_fields.
+          # Under a write root, what it answers with comes after what it did, whichever class it is.
+          def self.open?(field, write_root: false)
+            resolver = field.resolver
+            return false if resolver.nil? || resolver.respond_to?(:armory_rule)
+            return false if field.respond_to?(:armory_declared) && !field.armory_declared.nil?
+            return false if ruled_owner?(field.owner)
+
+            write_root || !refused_by_its_type?(field, resolver)
+          end
+
+          def self.ruled_owner?(owner)
+            return false unless owner.is_a?(Class) && owner <= GraphQL::Schema::Resolver && owner.respond_to?(:armory_rule)
+
+            rule = owner.armory_rule
+            # With on_denied: :errors a refusal answers a live payload, so its fields still run.
+            !rule.nil? && !rule.none? && owner.armory_on_denied != :errors
+          end
+          private_class_method :ruled_owner?
+
+          # What a plain read answers with is refused by the rule of that type. A mutation has already written by then, and an
+          # interface may gain an implementer with no rule. A type that does not load yet counts as neither.
+          def self.refused_by_its_type?(field, resolver)
+            return false if resolver <= GraphQL::Schema::Mutation || resolver <= GraphQL::Schema::Subscription
+
+            ruled?(field.type.unwrap)
+          rescue GraphQL::Error, NameError
+            false
+          end
+          private_class_method :refused_by_its_type?
+
+          def self.ruled?(element)
+            return generated_connection?(element) && ruled?(element.node_type) if Definitions.connection?(element)
+
+            if element.respond_to?(:kind) && element.kind.union?
+              members = element.type_memberships.map(&:object_type)
+              return !members.empty? && members.all? { |member| ruled?(member) }
+            end
+            return false unless element.is_a?(Class) && element.respond_to?(:armory_rule)
+
+            rule = element.armory_rule
+            !rule.nil? && !rule.none?
+          end
+          private_class_method :ruled?
+
+          # A field a connection or its edge adds is served by that class, whatever the rule on its nodes.
+          def self.generated_connection?(connection)
+            fields = Definitions.fields_at_every_level(connection)
+            edges = fields.select { |field| field.original_name == :edges }.map { |field| field.type.unwrap }
+            only_generated?(fields, GENERATED_RELAY_FIELDS.fetch(GraphQL::Types::Relay::BaseConnection)) &&
+              edges.all? { |edge| only_generated?(Definitions.fields_at_every_level(edge), GENERATED_RELAY_FIELDS.fetch(GraphQL::Types::Relay::BaseEdge)) }
+          end
+          private_class_method :generated_connection?
+
+          def self.only_generated?(fields, names)
+            fields.all? { |field| names.include?(field.original_name) && field.resolver.nil? }
+          end
+          private_class_method :only_generated?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Audit
+        # What a problem reaches beyond its own name: every definition that is, inherits from or implements what its path
+        # names, with their fields and `loads:`. A problem on a type or a base class says nothing about what is added to it
+        # later, so a baseline compares this to tell the problem someone accepted from a larger one.
+        class Reach
+          LIBRARY = [::Object, ::BasicObject, ::Kernel, ::Comparable].freeze
+
+          def initialize(definitions)
+            @definitions = definitions
+          end
+
+          def call(path)
+            head, member = path.delete_suffix(")").split(/[.(]/)
+            @definitions.select { |type| holds?(type, head) }.flat_map { |type| of(type, member) }.sort
+          end
+
+          private
+
+          def holds?(type, head)
+            type.graphql_name == head || type.ancestors.any? { |ancestor| app_class?(ancestor) && (ancestor.name == head || named?(ancestor, head)) }
+          end
+
+          # Ruby's and graphql-ruby's own classes are in every type's ancestors, and graphql-ruby's answer `graphql_name` too: a
+          # type named `Object` or `Member` must not reach everything.
+          def app_class?(ancestor)
+            !LIBRARY.include?(ancestor) && !ancestor.name&.start_with?("GraphQL::")
+          end
+
+          def named?(ancestor, head)
+            ancestor.respond_to?(:graphql_name) && ancestor.graphql_name == head
+          rescue GraphQL::Error
+            false # an anonymous class with no name of its own
+          end
+
+          # A problem on one field reaches that field: the others of its type have their own problems.
+          def of(type, member)
+            label = type.name || type.graphql_name
+            return ["type:#{label}", *input_loads(label, type)] if type.kind.input_object?
+            return ["type:#{label}"] unless type.respond_to?(:fields)
+
+            fields = Definitions.fields_at_every_level(type)
+            fields = fields.select { |field| field.graphql_name == member || field.original_name.to_s == member } if member
+            ["type:#{label}", *fields.flat_map { |field| of_field(label, field) }]
+          end
+
+          def input_loads(label, type)
+            type.all_argument_definitions.filter_map { |argument| argument.loads && "loads:#{label}.#{argument.graphql_name}:#{argument.loads.graphql_name}" }
+          end
+
+          def of_field(label, field)
+            ["field:#{label}.#{field.graphql_name}:#{signature(field)}",
+             *field.all_argument_definitions.filter_map { |argument| loads_of(label, field, argument) }]
+          end
+
+          # A field whose type cannot be read is what some problems are about: it must not stop the audit.
+          def signature(field)
+            field.type.to_type_signature
+          rescue StandardError, LoadError
+            "unreadable"
+          end
+
+          def loads_of(label, field, argument)
+            loads = argument.loads
+            "loads:#{label}.#{field.graphql_name}.#{argument.graphql_name}:#{loads.graphql_name}" if loads
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -16,12 +16,18 @@ module GraphQL
 
           attr_reader :problems, :bypasses
 
-          def initialize(problems:, bypasses:)
+          def initialize(problems:, bypasses:, reach: nil)
             @problems = problems.freeze
             @bypasses = bypasses.freeze
+            @reach = reach
             freeze
           end
 
+          # What a problem reaches beyond its own name: see Reach. Worked out only for a baseline, so a plain audit never reads it.
+          def reach_of(problem)
+            @reach ? @reach.(problem.path) : []
+          end
+
           def ok?
             problems.empty?
           end

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

@@ -6,7 +6,8 @@ module GraphQL
       class Audit
         # An object type's rule, and what its fields, resolvers and arguments declare under it.
         class TypeRules
-          def initialize(adapter = Adapters::Null.new, findings = Findings.new, foreign_policies = ForeignPolicies.new(adapter, findings))
+          def initialize(adapter = Adapters::Null.new, findings = Findings.new, foreign_policies = ForeignPolicies.new(adapter, findings), write_roots = [])
+            @write_roots = write_roots
             @adapter = adapter
             @findings = findings
             @foreign_policies = foreign_policies
@@ -87,6 +88,7 @@ module GraphQL
             audit_loads(field, path)
             # An inherited interface field is reported as uncovered on its interface; every other check still runs here.
             inherited = bypassed && interface_field?(field)
+            PlainResolvers.report(@findings, path, field) if served_with_no_rule?(type, field)
             if bypassed && !inherited && !field.respond_to?(:armory_declared)
               return @findings.problem(:field_without_rule, path, "its field class does not include Base, so no rule runs on it: its type is bypassed and graphql-ruby's own " \
                                                                   "authorized? answers true, so the field is served with no check. Use a field class that includes Base")
@@ -100,6 +102,13 @@ module GraphQL
             audit_arguments(field.all_argument_definitions, path, reported: reported)
           end
 
+          # Asked of the type that serves it and of the class that defines it, as runtime does: a parent that does not cover it denies it.
+          def served_with_no_rule?(type, field)
+            return false unless PlainResolvers.covering?(type.armory_rule) && !interface_field?(field) && PlainResolvers.open?(field, write_root: @write_roots.include?(type))
+
+            !(field.respond_to?(:armory_denied_by_owner?) && field.armory_denied_by_owner?)
+          end
+
           # A field runs under its owner: graphql-ruby never tells it the concrete type. A rule defined above that type asks
           # the owner's model, or only the record's class, while this audit reads the type's model.
           def audit_inherited_rule(type, field, path, model)
@@ -153,7 +162,10 @@ module GraphQL
             when :none
               @findings.bypass(path, field.armory_reason)
             when nil, true
-              if bypassed && declared.nil? && served_by_owner?(type, field)
+              if denied_payload_field?(field)
+                @findings.problem(:field_without_rule, path, "declares no rule and #{name_of(field.owner)}, which defines it, has none that covers it, so the mutation runs and this field answers null: " \
+                                                             "a client cannot tell whether it worked. Give the field `authorize: :none, reason: \"...\"`, or use a shared `payload_type`; a public mutation adds `covers_fields: true`")
+              elsif bypassed && declared.nil? && served_by_owner?(type, field)
                 @findings.problem(:field_without_rule, path, "declares no rule and its type is bypassed, but it is inherited from #{field.owner.name || field.owner.inspect}: a field runs " \
                                                              "under the class that defines it, and no rule ran on this type, so the field is served with no check. Give it authorize: where it is defined, or remove it")
               elsif bypassed
@@ -164,6 +176,11 @@ module GraphQL
             end
           end
 
+          def denied_payload_field?(field)
+            owner = field.owner
+            owner.is_a?(Class) && owner <= GraphQL::Schema::Resolver && field.armory_denied_by_owner?
+          end
+
           # A field runs under its owner's rule, not the resolved type's. Inherited by a bypassed type from a parent whose
           # rule covers it, or that knows no rule at all, graphql-ruby serves it after a type check that checked nothing.
           def served_by_owner?(type, field)

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

@@ -2,16 +2,21 @@
 
 require "set"
 require "graphql/armory/authorization/audit/report"
+require "graphql/armory/authorization/audit/baseline"
+require "graphql/armory/authorization/audit/reach"
 require "graphql/armory/authorization/audit/command"
 require "graphql/armory/authorization/audit/findings"
 require "graphql/armory/authorization/audit/library_methods"
 require "graphql/armory/authorization/audit/denial_hooks"
 require "graphql/armory/authorization/audit/own_checks"
+require "graphql/armory/authorization/audit/plain_resolvers"
 require "graphql/armory/authorization/audit/overrides"
 require "graphql/armory/authorization/audit/foreign_policies"
 require "graphql/armory/authorization/audit/type_rules"
+require "graphql/armory/authorization/audit/observed_rules"
 require "graphql/armory/authorization/audit/edge_rules"
 require "graphql/armory/authorization/audit/interface_rules"
+require "graphql/armory/authorization/audit/payload_reuse"
 require "graphql/armory/authorization/audit/input_loads"
 require "graphql/armory/authorization/audit/visibility_models"
 require "graphql/armory/authorization/audit/introspection_fields"
@@ -64,16 +69,18 @@ module GraphQL
           end
 
           foreign_policies = ForeignPolicies.new(adapter, findings)
-          type_rules = TypeRules.new(adapter, findings, foreign_policies)
+          type_rules = TypeRules.new(adapter, findings, foreign_policies, [schema.mutation, schema.subscription].compact)
           audited_types(definitions).each { |type| type_rules.(type) }
           definitions.each { |type| foreign_policies.relay(type) if type.kind.object? && RELAY_TYPES.any? { |relay| type <= relay } }
           EdgeRules.(definitions, findings)
           InterfaceRules.(definitions, findings)
           InputLoads.(definitions, findings)
+          PayloadReuse.(definitions, findings)
+          ObservedRules.(schema, definitions, findings)
           VisibilityModels.(schema, definitions, findings)
           IntrospectionFields.(schema, findings)
           findings.problem(:model, "Schema", listing_error.message) if listing_error && !findings.problem?(:model)
-          findings.report
+          findings.report(Reach.new(definitions))
         end
 
         private
@@ -84,10 +91,11 @@ module GraphQL
             Definitions.fields_at_every_level(type).any? { |field| !field.owner.equal?(GraphQL::Types::Relay::PageInfo) }
         end
 
-        # A connection or an edge holds only what graphql-ruby generates, until a subclass, its parent or an interface adds a field.
+        # A connection or an edge holds only what graphql-ruby generates, until a subclass, its parent or an interface adds a field,
+        # or gives a generated name a resolver of its own.
         def extended_relay?(type)
           GENERATED_RELAY_FIELDS.any? do |relay, names|
-            type < relay && Definitions.fields_at_every_level(type).any? { |field| !names.include?(field.original_name) }
+            type < relay && Definitions.fields_at_every_level(type).any? { |field| !names.include?(field.original_name) || field.resolver }
           end
         end
 

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

@@ -14,24 +14,42 @@ module GraphQL
           @telemetry = telemetry
         end
 
-        def self.build(context, adapter:, sinks: [])
-          new(adapter: adapter, memo: Memo.build(context), telemetry: Telemetry.build(sinks: sinks))
+        def self.build(context, adapter:, sinks: [], on_sink_error: nil)
+          new(adapter: adapter, memo: Memo.build(context), telemetry: Telemetry.build(sinks: sinks, on_sink_error: on_sink_error))
         end
 
-        def self.call(subject, rule, context, adapter:, sinks: [])
-          build(context, adapter: adapter, sinks: sinks).(subject, rule, context)
+        def self.call(subject, rule, context, adapter:, sinks: [], on_sink_error: nil)
+          build(context, adapter: adapter, sinks: sinks, on_sink_error: on_sink_error).(subject, rule, context)
         end
 
         def call(subject, rule, context)
-          return bypass(subject, rule) if rule.none?
+          return bypass(subject, rule, context) if rule.none?
 
           memo.fetch(subject, rule) { decide(subject, rule, context) }
         end
 
         private
 
-        def bypass(subject, rule)
-          telemetry.record(:bypassed, type: class_name(subject), reason: rule.reason)
+        def bypass(subject, rule, context)
+          telemetry.record(:bypassed, context: context, type: class_name(subject), reason: rule.reason)
+          true
+        end
+
+        # Observing opens one thing only: a clear "no" to a read, with someone listening, from an adapter someone configured.
+        # A mutation or a subscription keeps refusing, even on a read inside its response: only a query runs nothing it cannot undo.
+        def observes?(rule, context)
+          rule.observed? && telemetry.listening? && !adapter.is_a?(Adapters::Null) && read_only?(context)
+        end
+
+        # A partial always answers `query?`, whatever the operation that ran it: only the query it came from can tell.
+        def read_only?(context)
+          query = context.query if context.respond_to?(:query)
+          query = query.query while defined?(GraphQL::Query::Partial) && query.is_a?(GraphQL::Query::Partial)
+          query.respond_to?(:query?) && query.query? == true
+        end
+
+        def observe(subject, rule, context)
+          telemetry.record(:observed, context: context, type: class_name(subject), action: rule.action, reason: rule.observe)
           true
         end
 
@@ -45,8 +63,10 @@ module GraphQL
 
           case answer
           when true, false, nil
+            return observe(subject, rule, context) if answer != true && observes?(rule, context)
+
             allowed = answer == true
-            telemetry.record(allowed ? :allowed : :denied, type: class_name(subject), action: rule.action)
+            telemetry.record(allowed ? :allowed : :denied, context: context, type: class_name(subject), action: rule.action)
             allowed
           else
             # The class alone: the answer may be the record, and on a relation `inspect` runs the query.

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

@@ -11,9 +11,9 @@ module GraphQL
 
         OWN_CHECKS = %i[authorized? authorizes? authorized_new wrap unauthorized_object visible? scope_items reauthorize_scoped_objects].freeze
 
-        attr_reader :adapter, :on_unauthorized, :sinks, :own_denial_hooks, :own_checks
+        attr_reader :adapter, :on_unauthorized, :sinks, :on_sink_error, :own_denial_hooks, :own_checks
 
-        def initialize(adapter:, on_unauthorized: :null, sinks: [], own_denial_hooks: {}, own_checks: {})
+        def initialize(adapter:, on_unauthorized: :null, sinks: [], on_sink_error: nil, own_denial_hooks: {}, own_checks: {})
           unless MODES.include?(on_unauthorized)
             raise ArgumentError, "on_unauthorized must be one of #{MODES.inspect}, got #{on_unauthorized.inspect}"
           end
@@ -24,8 +24,9 @@ module GraphQL
           @adapter = resolve(adapter)
           @on_unauthorized = on_unauthorized
           @own_denial_hooks = own_denial_hooks.to_h { |hook, reason| [hook, reason.dup.freeze] }.freeze
-          Telemetry.build(sinks: sinks) # raises at boot when the sinks are not callables
+          Telemetry.build(sinks: sinks, on_sink_error: on_sink_error) # raises at boot when the sinks are not callables
           @sinks = sinks
+          @on_sink_error = on_sink_error
         end
 
         private

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

@@ -66,12 +66,19 @@ module GraphQL
           references << arguments_of(type) if type.kind.input_object?
           references.concat(type.interface_type_memberships.map(&:abstract_type)) if type.respond_to?(:interface_type_memberships)
           references.concat(type.orphan_types) if type.kind.interface?
+          references.concat(included_interfaces(type)) if type.kind.interface?
           references.concat(type.type_memberships.map(&:object_type)) if type.kind.union?
           references << type.node_type if connection?(type)
           references.flatten.compact
         end
         private_class_method :referenced_types
 
+        # An interface brought in with `include` makes no type membership, and its fields are served all the same.
+        def self.included_interfaces(type)
+          type.ancestors.select { |ancestor| !ancestor.equal?(type) && ancestor.respond_to?(:kind) && ancestor.kind.interface? }
+        end
+        private_class_method :included_interfaces
+
         # Every definition of every field, nearest first: a hidden one falls back to the next of its name, and
         # `all_field_definitions` merges them by name. `field ... do ... end` blocks are loaded here, because only
         # `schema.types` or a request loads them, and the audit reads arguments from them.

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

@@ -10,6 +10,7 @@ module GraphQL
         #   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
+        #   field :notes, String, authorize: :manage, observe: "rollout"  # served and recorded, see Authorize
         #
         # 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.
@@ -19,9 +20,16 @@ module GraphQL
         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, override_reason: nil, **kwargs, &block)
+          def initialize(*args, authorize: nil, reason: nil, observe: nil, find_by: nil, load_through_scope: true, visible_when: nil, override_reason: nil, **kwargs, &block)
             raise ConfigurationError, "override_reason: must say why the override is safe" if !override_reason.nil? && override_reason.to_s.strip.empty?
 
+            if !observe.nil? && (!authorize.is_a?(Symbol) || authorize == :none)
+              raise ArgumentError, "observe: needs an action of the field's own: `authorize: :manage, observe: \"...\"`"
+            end
+            raise ArgumentError, "observe: does not apply to a field with a resolver or a mutation: what it runs cannot be undone" if !observe.nil? && kwargs[:resolver_class]
+            Rule.new(authorize, observe: observe) unless observe.nil?
+
+            @armory_observe = observe
             @armory_override_reason = override_reason
             @armory_declared = authorize
             @armory_reason = reason
@@ -32,7 +40,7 @@ module GraphQL
             extension(Integration::FindBy, key: find_by) if find_by
           end
 
-          attr_reader :armory_declared, :armory_reason, :armory_visible_when, :armory_override_reason
+          attr_reader :armory_declared, :armory_reason, :armory_observe, :armory_visible_when, :armory_override_reason
 
           def armory_load_through_scope?
             @armory_load_through_scope
@@ -72,10 +80,24 @@ module GraphQL
           def authorized?(object, args, context)
             rule = armory_rule_for(owner, context)
             return false if rule.nil?
+            if resolver && rule.is_a?(Rule) && rule.observed?
+              raise ConfigurationError, "#{owner.graphql_name}.#{graphql_name} has a resolver or a mutation, which can write, so it cannot use an observed rule"
+            end
 
             (rule == :covered || Integration.allowed?(object, Integration.with_owner_model(rule, owner), context)) && super
           end
 
+          # Asked of a field with no resolver. True when it declares no rule of its own and the class that declared it does not cover it. It asks that class
+          # and not the type being served: a field a payload inherits keeps the parent mutation as its owner.
+          def armory_denied_by_owner?
+            return false unless [nil, true].include?(@armory_declared) && owner.respond_to?(:armory_rule)
+
+            rule = owner.armory_rule
+            return true if rule.nil?
+
+            @armory_declared.nil? ? rule.none? && !rule.covers_fields? : rule.none?
+          end
+
           private
 
           # A resolver or mutation that includes Base enforces its own rule, so the field is covered by it.
@@ -94,13 +116,13 @@ module GraphQL
               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
+              armory_denied_by_owner? ? nil : :covered
             when true
               type_rule unless type_rule&.none?
             when :none
               Rule.none(reason: @armory_reason)
             else
-              Rule.new(@armory_declared, policy: armory_policy, attribute: original_name)
+              Rule.new(@armory_declared, policy: armory_policy, attribute: original_name, observe: @armory_observe)
             end
           end
         end

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

@@ -60,7 +60,15 @@ module GraphQL
             rule = armory_rule
             return false if rule.nil?
 
+            Integration.refuse_unobservable(self, context) if rule.observed?
             Integration.allowed?(object, Integration.with_owner_model(rule, self), context) && super
+          rescue GraphQL::UnauthorizedError
+            raise
+          rescue StandardError => error
+            # graphql-ruby reads what a rescue_from answers here as the authorization, on both engines, so a handler that logs
+            # and answers true would serve the object. The handler runs, its answer does not count. No public hook does this.
+            context.query.handle_or_reraise(error)
+            false
           end
         end
       end

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

@@ -21,6 +21,8 @@ module GraphQL
           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)
 
+            raise ArgumentError, "observe: does not apply to a mutation or a resolver: what it runs cannot be undone" if options.key?(:observe)
+
             @armory_on_denied = on_denied
             @armory_rule = Rule.new(action, reason: reason, **options)
           end