graphql-armory 0.1.0.pre8 → 0.1.0.pre9

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

@@ -41,7 +41,7 @@ module GraphQL
           return Adapters::Null.new.scope(nil, items, rule) if rule.nil?
 
           configuration = configuration(context)
-          Scope.(items, rule, context, adapter: configuration.adapter, sinks: configuration.sinks)
+          Scope.(items, rule, context, adapter: configuration.adapter, sinks: configuration.sinks, on_sink_error: configuration.on_sink_error)
         end
 
         # Looks an object up inside the user's scope, by primary key unless a key is given.
@@ -60,7 +60,7 @@ module GraphQL
 
           # 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)
+          record if record && allowed?(record, rule.enforced, context)
         end
 
         # Loads a `loads:` argument inside the user's scope. When the schema defines `object_from_id` (global
@@ -124,12 +124,23 @@ module GraphQL
         end
         private_class_method :declared_model
 
+        # Observing a type opens the only check that stands before everything inside it, whatever class its fields are. A
+        # resolver or a mutation can write, and a write cannot be undone, so a type holding one cannot be observed.
+        def self.refuse_unobservable(type, context)
+          known = context.namespace(:armory)[:observable] ||= {}.compare_by_identity
+          field = known.fetch(type) { known[type] = type.all_field_definitions.find(&:resolver) }
+          return unless field
+
+          raise ConfigurationError, "#{type.graphql_name} cannot be observed: its field #{field.graphql_name} has a resolver or a mutation, which can write. " \
+                                    "Remove observe:, or put it on its plain fields"
+        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)
+            Authorize.build(context, adapter: configuration.adapter, sinks: configuration.sinks, on_sink_error: configuration.on_sink_error)
           end
 
           authorize.(subject, rule, context)

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

@@ -5,10 +5,16 @@ 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
+#   expect(AppSchema).to be_fully_authorized(baseline: "config/graphql_armory_baseline.json")   # fails only on new problems
+RSpec::Matchers.define :be_fully_authorized do |*positional, baseline: nil|
+  raise ArgumentError, "be_fully_authorized takes baseline: path" unless positional.empty?
+
   match do |schema|
-    @report = GraphQL::Armory::Authorization::Audit.(schema)
-    @report.ok?
+    report = GraphQL::Armory::Authorization::Audit.(schema)
+    next (@report = report).ok? unless baseline
+
+    @report = GraphQL::Armory::Authorization::Audit::Baseline.load(baseline).(report)
+    @report.passes?
   end
 
   failure_message do |schema|
@@ -16,6 +22,6 @@ RSpec::Matchers.define :be_fully_authorized do
   end
 
   failure_message_when_negated do |schema|
-    "expected #{schema} not to be fully authorized, but the audit found no problems"
+    baseline ? "expected #{schema} not to pass its baseline, but it did:\n#{@report}" : "expected #{schema} not to be fully authorized, but the audit found no problems"
   end
 end

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

@@ -6,13 +6,13 @@ module GraphQL
       # 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
+        attr_reader :action, :policy, :subject, :attribute, :model, :scope, :visible_when, :covers_fields, :reason, :observe
 
         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)
+        def initialize(action, policy: nil, subject: nil, attribute: nil, model: nil, scope: nil, visible_when: nil, covers_fields: false, reason: nil, observe: nil)
           raise ArgumentError, "a rule needs an action" if action.nil?
 
           @action = action.to_sym
@@ -24,19 +24,35 @@ module GraphQL
           @visible_when = visible_when&.to_sym
           @covers_fields = covers_fields
           @reason = reason
+          @observe = observe
 
           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?
+          raise ArgumentError, "observe: needs a text saying why this rule is observed, got #{observe.class}" unless observe.nil? || (observe.is_a?(String) && !observe.strip.empty?)
+          raise ArgumentError, "observe: does not apply to a bypass, which refuses nothing" if observe && none?
 
           freeze
         end
 
         def with_model(model)
+          self.class.new(action, policy: policy, subject: subject, attribute: attribute, model: model, scope: scope,
+                                 visible_when: visible_when, covers_fields: covers_fields, reason: reason, observe: observe)
+        end
+
+        # The same rule with no observation, for what must keep refusing: lookups through a scope.
+        def enforced
+          return self unless observed?
+
           self.class.new(action, policy: policy, subject: subject, attribute: attribute, model: model, scope: scope,
                                  visible_when: visible_when, covers_fields: covers_fields, reason: reason)
         end
 
+        # A clear "no" to this rule, on a read, is served and recorded instead of refused. See Authorize.
+        def observed?
+          !observe.nil?
+        end
+
         # A bypassed type whose fields are covered by something else, such as the payload of a mutation.
         def covers_fields?
           covers_fields
@@ -58,7 +74,7 @@ module GraphQL
         protected
 
         def members
-          [action, policy, subject, attribute, model, scope, visible_when, covers_fields, reason]
+          [action, policy, subject, attribute, model, scope, visible_when, covers_fields, reason, observe]
         end
       end
     end

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

@@ -13,22 +13,22 @@ module GraphQL
           @telemetry = telemetry
         end
 
-        def self.build(adapter:, sinks: [])
-          new(adapter: adapter, telemetry: Telemetry.build(sinks: sinks))
+        def self.build(adapter:, sinks: [], on_sink_error: nil)
+          new(adapter: adapter, telemetry: Telemetry.build(sinks: sinks, on_sink_error: on_sink_error))
         end
 
-        def self.call(items, rule, context, adapter:, sinks: [])
-          build(adapter: adapter, sinks: sinks).(items, rule, context)
+        def self.call(items, rule, context, adapter:, sinks: [], on_sink_error: nil)
+          build(adapter: adapter, sinks: sinks, on_sink_error: on_sink_error).(items, rule, context)
         end
 
         def call(items, rule, context)
           if rule.none?
-            telemetry.record(:bypassed, reason: rule.reason)
+            telemetry.record(:bypassed, context: context, reason: rule.reason)
             return items
           end
 
           scoped = adapter.scope(adapter.actor(context), items, rule)
-          telemetry.record(:scoped, action: rule.action)
+          telemetry.record(:scoped, context: context, action: rule.action)
           scoped
         end
       end

data/lib/graphql/armory/authorization.rb

@@ -36,7 +36,7 @@ module GraphQL
     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), `own_checks:` (an app's own `authorized?`, `authorizes?`, `authorized_new`, `wrap`,
+      # `sinks:` (callables that receive each telemetry signal), `on_sink_error:` (called with the error and the signal when a sink raises), `own_checks:` (an app's own `authorized?`, `authorizes?`, `authorized_new`, `wrap`,
       # `unauthorized_object`, `visible?`, `scope_items` or `reauthorize_scoped_objects(false)` on a class, with the reason, for the audit), `own_denial_hooks:` (the schema's own
       # `unauthorized_field` or `unauthorized_object`, each with the reason, for the audit).
       def self.use(schema_defn, **options)

data/lib/graphql/armory/ids.rb

@@ -16,8 +16,8 @@ module GraphQL
     module IDs
       SEPARATOR = "/"
 
-      def self.use(schema, encoder: nil, find: nil, sinks: [])
-        lookup = Lookup.build(encoder: encoder, find: find, sinks: sinks)
+      def self.use(schema, encoder: nil, find: nil, sinks: [], on_sink_error: nil)
+        lookup = Lookup.build(encoder: encoder, find: find, sinks: sinks, on_sink_error: on_sink_error)
         schema.define_singleton_method(:id_from_object) { |object, type, _context| lookup.id_for(object, type) }
         schema.define_singleton_method(:object_from_id) { |id, context| lookup.object_for(id, context) }
       end
@@ -27,8 +27,8 @@ module GraphQL
         attr_reader :encoder, :find, :telemetry
 
         # Wires the default encoder unless one is given; `use` goes through here.
-        def self.build(encoder: nil, find: nil, sinks: [])
-          new(encoder: encoder || Encoder.default, find: find, telemetry: Telemetry.build(sinks: sinks))
+        def self.build(encoder: nil, find: nil, sinks: [], on_sink_error: nil)
+          new(encoder: encoder || Encoder.default, find: find, telemetry: Telemetry.build(sinks: sinks, on_sink_error: on_sink_error))
         end
 
         # `new` is inert: with no encoder wired it hands out no ID and honours none. It checks what it is given.
@@ -52,25 +52,25 @@ module GraphQL
 
         def object_for(id, context)
           type_name, key = encoder.decode(id).split(SEPARATOR, 2)
-          return refuse(:malformed) if key.nil? || key.empty?
+          return refuse(:malformed, context) if key.nil? || key.empty?
 
           type = visible_type(type_name, context)
-          return refuse(:unknown_type) unless node_type?(type)
+          return refuse(:unknown_type, context) unless node_type?(type)
 
           object = load(type, key, context)
-          return refuse(:not_found, type: type.graphql_name) if object.nil?
+          return refuse(:not_found, context, type: type.graphql_name) if object.nil?
 
-          telemetry.record(:id_resolved, type: type.graphql_name)
+          telemetry.record(:id_resolved, context: context, type: type.graphql_name)
           object
         rescue Encoder::InvalidError
-          refuse(:invalid)
+          refuse(:invalid, context)
         end
 
         private
 
         # Every refusal answers nil, like a missing record; the signal says why, never which ID.
-        def refuse(reason, **data)
-          telemetry.record(:id_refused, reason: reason, **data)
+        def refuse(reason, context, **data)
+          telemetry.record(:id_refused, context: context, reason: reason, **data)
           nil
         end
 

data/lib/graphql/armory/persisted_queries/manifest.rb

@@ -17,6 +17,8 @@ module GraphQL
 
         Operation = Struct.new(:id, :name, :body, :document, keyword_init: true)
 
+        attr_reader :operations
+
         def self.load(path, digest: :sha256)
           data = begin
             JSON.parse(File.read(path, mode: "r:bom|utf-8"))

data/lib/graphql/armory/persisted_queries/manifests.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module PersistedQueries
+      # Several manifests behind one `store:`: each frontend's build, and every mobile version still in use.
+      #
+      #   use GraphQL::Armory::PersistedQueries, store: Manifests.build("config/persisted_queries/*.json"), strict: true
+      #
+      # A client's id is looked up across all of them, so any client may run any manifest's operation: they are one
+      # allowlist, not one per client. Any problem raises at boot.
+      class Manifests
+        GLOB = /[*?\[{]/
+
+        # `paths` is a glob pattern, a path, or a list of them. One that finds nothing raises: in strict mode its clients
+        # would all be refused. A glob skips dotfiles, and drops a missing `{a,b}` alternative: list exact paths to be sure.
+        def self.build(paths, digest: :sha256)
+          names = paths.is_a?(Array) ? paths : [paths]
+          raise ConfigurationError, "no manifest found in an empty list" if names.empty?
+
+          files = names.flat_map { |name| files_of(name) }.uniq
+          new(files.map { |file| Manifest.load(file, digest: digest) })
+        end
+
+        def self.files_of(name)
+          raise ConfigurationError, "manifest paths must be Strings or Pathnames, found a #{name.class}" unless name.is_a?(String) || name.respond_to?(:to_path)
+
+          path = name.is_a?(String) ? name : name.to_path
+          return [path] unless path.match?(GLOB)
+
+          found = Dir.glob(path).sort
+          found = [path] if found.empty? && File.file?(path) # a name with a `[`, which matched nothing as a pattern
+          raise ConfigurationError, "no manifest found in #{path}" if found.empty?
+
+          found
+        end
+        private_class_method :files_of
+
+        # `new` is inert: with no manifests it holds no operation, so every id is unknown.
+        def initialize(manifests = [])
+          unless manifests.is_a?(Array) && manifests.all? { |manifest| manifest.instance_of?(Manifest) }
+            raise ConfigurationError, "manifests must be an Array of Manifest; use Manifests.build for paths"
+          end
+
+          @operations = manifests.each_with_object({}) do |manifest, operations|
+            manifest.operations.each do |id, operation|
+              kept = operations[id] ||= operation
+              next if kept.body == operation.body
+
+              raise ConfigurationError, "two manifests hold different queries for #{id.match?(Manifest::ID_LIKE) ? "the id #{id}" : "one id"}"
+            end
+          end.freeze
+        end
+
+        def fetch(id)
+          @operations[id]
+        end
+
+        def size
+          @operations.size
+        end
+
+        def empty?
+          @operations.empty?
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/persisted_queries/publisher.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module GraphQL
+  module Armory
+    module PersistedQueries
+      # Publishes a client build's manifest to Redis, for `RedisStore` to read. It only adds: an id that already holds
+      # another query raises and stays as it was. Publishing again is safe, so a failed run can simply run again.
+      #
+      #   GraphQL::Armory::PersistedQueries::Publisher.call(Manifest.load("manifest.json"), redis: Redis.new(url: url))
+      class Publisher
+        # An id it could not store, or that holds another query. The message quotes neither query.
+        class PublishError < Armory::Error; end
+
+        Result = Struct.new(:published, :unchanged, keyword_init: true)
+
+        def self.build(redis:, prefix: RedisStore::DEFAULT_PREFIX)
+          raise ConfigurationError, "redis: must answer get and set, like Redis.new from the redis gem" unless redis.respond_to?(:get) && redis.respond_to?(:set)
+          raise ConfigurationError, "prefix: must be a non-empty String, got #{prefix.inspect}" unless prefix.is_a?(String) && !prefix.empty?
+
+          new(redis: redis, prefix: prefix)
+        end
+
+        def self.call(manifest, **options)
+          build(**options).(manifest)
+        end
+
+        # `new` is inert: with no Redis wired, nothing is stored and `call` raises.
+        def initialize(redis: RedisStore::Client::Null.new, prefix: RedisStore::DEFAULT_PREFIX)
+          @redis = redis
+          @prefix = prefix
+        end
+
+        def call(manifest)
+          raise ConfigurationError, "publish a Manifest: Manifest.load checks every id and query" unless manifest.instance_of?(Manifest)
+
+          check_ids(manifest)
+          published = manifest.operations.count { |id, operation| publish(id, operation.body) }
+          Result.new(published: published, unchanged: manifest.size - published)
+        end
+
+        private
+
+        # Before anything is stored: `RedisStore` never asks for an id of another shape.
+        def check_ids(manifest)
+          manifest.operations.keys.each_with_index do |id, index|
+            raise ConfigurationError, "the operation at entry #{index} has an id RedisStore cannot read" unless id.match?(Manifest::ID_LIKE)
+          end
+        end
+
+        # Answers whether it was new. SET NX, so two runs at once cannot overwrite each other.
+        def publish(id, body)
+          key = "#{@prefix}#{id}"
+          return true if @redis.set(key, body, nx: true)
+
+          stored = @redis.get(key)
+          raise PublishError, "operation #{id} was not stored" if stored.nil?
+          raise PublishError, "operation #{id} already holds another query: published operations never change" unless stored.b == body.b
+
+          false
+        end
+
+        # The `graphql-armory-publish` executable, for a client's CI. Answers the exit code. Redis's messages may hold
+        # the URL and its password, so only the error's class is printed.
+        class Command
+          USAGE = "Usage: graphql-armory-publish [--digest sha256|sha1|md5|false] [--prefix PREFIX] MANIFEST...\nReads REDIS_URL."
+
+          def self.call(argv = ARGV, env: ENV, out: $stdout, err: $stderr, client: nil)
+            new(env: env, out: out, err: err, client: client).(argv)
+          end
+
+          def initialize(env: {}, out: $stdout, err: $stderr, client: nil)
+            @env = env
+            @out = out
+            @err = err
+            @client = client
+          end
+
+          def call(argv)
+            digest, prefix, paths = options(argv)
+            return fail_with(USAGE) if paths.empty?
+
+            url = @env["REDIS_URL"]
+            return fail_with("REDIS_URL is not set") if url.to_s.empty?
+
+            manifests = paths.map { |path| [path, Manifest.load(path, digest: digest)] }
+            publisher = Publisher.build(redis: @client || redis(url), prefix: prefix)
+            manifests.each do |path, manifest|
+              result = publisher.(manifest)
+              @out.puts "#{path}: #{result.published} published, #{result.unchanged} unchanged"
+            end
+            0
+          rescue OptionParser::ParseError, Armory::Error => error
+            fail_with(error.message)
+          rescue LoadError
+            fail_with("graphql-armory-publish needs the redis gem: gem install redis")
+          rescue StandardError => error
+            fail_with("publishing failed (#{error.class})")
+          end
+
+          private
+
+          def options(argv)
+            digest = :sha256
+            prefix = RedisStore::DEFAULT_PREFIX
+            paths = OptionParser.new do |parser|
+              parser.on("--digest NAME") { |name| digest = name == "false" ? false : name.to_sym }
+              parser.on("--prefix PREFIX") { |given| prefix = given }
+            end.parse(argv)
+            [digest, prefix, paths]
+          end
+
+          def redis(url)
+            require "redis"
+            Redis.new(url: url)
+          end
+
+          def fail_with(message)
+            @err.puts message
+            1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/persisted_queries/redis_store.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module PersistedQueries
+      # Operations a client's CI published with `Publisher`, read while the server runs, so a new frontend needs no
+      # server deploy.
+      #
+      #   store = GraphQL::Armory::PersistedQueries::RedisStore.build(redis: Redis.new(url: ENV.fetch("REDIS_URL")))
+      #
+      # An operation it read stays in memory: published operations never change, so what it already knows keeps working
+      # when Redis fails. An id it cannot find, or cannot check, is unknown: nothing runs. This gem does not depend on
+      # the redis gem: the app adds it.
+      class RedisStore
+        DEFAULT_PREFIX = "graphql-armory:persisted-queries:"
+        DEFAULT_ON_ERROR = ->(error) { warn "graphql-armory: persisted query store failed (#{error.class})" }
+
+        # A stored value that does not parse, or is not the digest of its id. The message quotes neither.
+        class CorruptOperation < Armory::Error; end
+
+        # What the store and the publisher need from Redis.
+        module Client
+          # The Redis of a store nobody wired: it holds nothing and stores nothing.
+          class Null
+            def get(_key)
+              nil
+            end
+
+            def set(_key, _value, nx: false)
+              nil
+            end
+          end
+
+          # Holds its keys in memory like Redis, records its calls and fails when told: for tests.
+          class Substitute
+            attr_reader :calls
+
+            def initialize
+              @data = {}
+              @calls = []
+              @failure = nil
+            end
+
+            # Raises `error` from every call until `recover`.
+            def fail_with(error)
+              @failure = error
+            end
+
+            def recover
+              @failure = nil
+            end
+
+            def get(key)
+              @calls << [:get, key]
+              raise @failure if @failure
+
+              @data[key]
+            end
+
+            def set(key, value, nx: false)
+              @calls << [:set, key]
+              raise @failure if @failure
+              return false if nx && @data.key?(key)
+
+              @data[key] = value
+              true
+            end
+          end
+        end
+
+        # Validates the settings and wires the real Redis client.
+        def self.build(redis:, prefix: DEFAULT_PREFIX, digest: :sha256, on_error: DEFAULT_ON_ERROR)
+          raise ConfigurationError, "redis: must answer get and set, like Redis.new from the redis gem" unless redis.respond_to?(:get) && redis.respond_to?(:set)
+          raise ConfigurationError, "prefix: must be a non-empty String, got #{prefix.inspect}" unless prefix.is_a?(String) && !prefix.empty?
+          unless digest == false || Manifest::DIGESTS.key?(digest)
+            raise ConfigurationError, "unknown digest #{digest.inspect}: use #{Manifest::DIGESTS.keys.map(&:inspect).join(", ")} or false"
+          end
+          raise ConfigurationError, "on_error: must be a callable that takes the error" unless on_error.respond_to?(:call)
+
+          new(redis: redis, prefix: prefix, digest: digest, on_error: on_error)
+        end
+
+        # `new` is inert: with no Redis wired it holds no operation, so every id is unknown.
+        def initialize(redis: Client::Null.new, prefix: DEFAULT_PREFIX, digest: :sha256, on_error: DEFAULT_ON_ERROR)
+          @redis = redis
+          @prefix = prefix
+          @digest = digest == false ? nil : Manifest::DIGESTS.fetch(digest)
+          @on_error = on_error
+          @operations = {}
+          @mutex = Mutex.new
+        end
+
+        def fetch(id)
+          # Bytes: a regexp raises on a client's broken encoding.
+          return unless id.is_a?(String) && id.b.match?(Manifest::ID_LIKE)
+
+          @operations[id] || read(id)
+        end
+
+        # Only an unwired store is known to be empty: `strict: false` refuses it at boot, as it does the Null store.
+        def empty?
+          @redis.is_a?(Client::Null)
+        end
+
+        private
+
+        # Only what it found is remembered: an unknown id may be published a moment later.
+        def read(id)
+          body = @redis.get("#{@prefix}#{id}")
+          return if body.nil?
+
+          operation = operation(id, body)
+          @mutex.synchronize { @operations[id] ||= operation }
+        rescue StandardError => error
+          @on_error.call(error)
+          nil
+        end
+
+        def operation(id, stored)
+          raise CorruptOperation, "operation #{id} is not text" unless stored.is_a?(String)
+
+          # redis-rb may answer in another encoding; a query compares as text with what the client sends.
+          body = stored.dup.force_encoding(Encoding::UTF_8).freeze
+          raise CorruptOperation, "operation #{id} is not the digest of its query" if @digest && @digest.hexdigest(body) != id
+
+          Manifest::Operation.new(id: id.dup.freeze, body: body, document: parse(id, body)).freeze
+        end
+
+        def parse(id, body)
+          GraphQL.parse(body)
+        rescue GraphQL::ParseError
+          raise CorruptOperation, "operation #{id} does not parse"
+        end
+      end
+    end
+  end
+end