graphql-armory 0.1.0.pre → 0.1.0.pre3

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

@@ -6,6 +6,7 @@ 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/input_object"
 require "graphql/armory/authorization/integration/base"
 
 module GraphQL
@@ -62,6 +63,37 @@ module GraphQL
           record if record && allowed?(record, rule, context)
         end
 
+        # Loads a `loads:` argument inside the user's scope. When the schema defines `object_from_id` (global
+        # IDs), it decodes the id; the record must be of the type's model, and is then looked up again
+        # through the scope, so a foreign id still looks like a missing one. Otherwise the id is the primary key.
+        def self.load(type, id, context)
+          schema = context.schema
+          return find(type, nil, id, context) unless decodes_ids?(schema) && type.respond_to?(:armory_model)
+
+          model = type.armory_model
+          record = decode(schema, id, context)
+          return nil unless record.is_a?(model)
+
+          find(type, nil, record.public_send(model.primary_key), context)
+        end
+
+        # `GlobalID.find`, graphql-ruby's documented `object_from_id`, raises for a missing record, and a
+        # decoder may raise for a malformed id (ArgumentError, or the Encoder's InvalidError). All must answer like a
+        # record out of scope: nil.
+        def self.decode(schema, id, context)
+          schema.object_from_id(id, context)
+        rescue StandardError => error
+          raise unless error.is_a?(ArgumentError) || error.is_a?(Encoder::InvalidError) || error.class.name == "ActiveRecord::RecordNotFound"
+
+          nil
+        end
+        private_class_method :decode
+
+        # graphql-ruby's default `object_from_id` only raises, so an override is the app decoding its IDs.
+        def self.decodes_ids?(schema)
+          schema.method(:object_from_id).owner != GraphQL::Schema.singleton_class
+        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)

data/lib/graphql/armory/encoder/default.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    class Encoder
+      ENV_KEY = "GRAPHQL_ARMORY_KEY"
+      RAILS_PURPOSE = "graphql-armory/ids"
+
+      # An encoder whose key comes from the app, never from the gem: `GRAPHQL_ARMORY_KEY`, or else a key derived
+      # with HKDF from Rails' secret_key_base for this purpose alone. Without either it raises, so the app fails
+      # when the schema loads instead of serving unencrypted IDs.
+      #
+      # It reads `secret_key_base` instead of `Rails.application.key_generator`: that generator is built once per
+      # process with whatever digest Rails has configured at that moment, which changes during boot, so the same
+      # secret could give different IDs in a web server and in a rake task (and calling it early would also fix
+      # Rails' own cookie keys to the wrong digest).
+      def self.default(env: ENV, rails: rails_application)
+        secret = env_key(env)
+        secret = rails_key(rails) if secret.nil? && rails
+        if secret.nil?
+          raise ConfigurationError,
+                "no key for the default encoder: set #{ENV_KEY} (try `ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`), " \
+                "or run inside a Rails app with a secret_key_base"
+        end
+
+        Class.new(self) { key(secret) }
+      end
+
+      def self.env_key(env)
+        value = env[ENV_KEY].to_s
+        return nil if value.empty?
+        if value.strip != value || value.strip.empty?
+          raise ConfigurationError, "#{ENV_KEY} has leading or trailing whitespace, or only whitespace: remove it"
+        end
+
+        value
+      end
+      private_class_method :env_key
+
+      def self.rails_application
+        ::Rails.application if defined?(::Rails) && ::Rails.respond_to?(:application)
+      end
+      private_class_method :rails_application
+
+      def self.rails_key(rails)
+        secret = begin
+          rails.secret_key_base
+        rescue StandardError => error
+          # Rails' message may come from app code; name only its class so nothing secret is echoed.
+          raise ConfigurationError, "the default encoder could not read Rails' secret_key_base (#{error.class})"
+        end
+        raise ConfigurationError, "this Rails app has no secret_key_base for the default encoder" if secret.to_s.empty?
+
+        OpenSSL::KDF.hkdf(secret.to_s, salt: "graphql-armory", info: RAILS_PURPOSE, length: 32, hash: "SHA256")
+      end
+      private_class_method :rails_key
+    end
+  end
+end

data/lib/graphql/armory/encoder/legacy.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module GraphQL
+  module Armory
+    class Encoder
+      # graphql-ruby's default base64, to keep reading the cursors and IDs clients already hold while migrating to
+      # encryption: put it last in `Encoder.versioned`. It reads base64 padded or not, url-safe or standard, and
+      # only when it holds printable text, so a tampered encrypted value never comes back as garbage. It is not
+      # encryption: anyone can forge what it reads. Remove it from the chain once old values have expired.
+      module Legacy
+        PRINTABLE = /\A[[:print:]]*\z/
+
+        def self.encode(text, nonce: false)
+          Base64.urlsafe_encode64(text.to_s, padding: false)
+        end
+
+        def self.decode(text, nonce: false)
+          raise InvalidError unless text.is_a?(String) && !text.empty?
+
+          plain = Base64.urlsafe_decode64(text.tr("+/", "-_").delete_suffix("==").delete_suffix("="))
+          raise InvalidError if plain.empty?
+          plain.force_encoding(Encoding::UTF_8)
+          raise InvalidError unless plain.valid_encoding? && plain.match?(PRINTABLE)
+
+          plain
+        rescue StandardError
+          raise InvalidError
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/encoder/versioned.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    class Encoder
+      # A chain of encoders, newest first: encodes with the first, decodes with whichever accepts the value.
+      # Build it with `Encoder.versioned(NewEncoder, OldEncoder, Encoder::Legacy)`.
+      class Versioned
+        attr_reader :encoders
+
+        def initialize(encoders)
+          raise ConfigurationError, "a versioned encoder needs at least one encoder" if encoders.empty?
+
+          encoders.each { |encoder| check(encoder) }
+          @encoders = encoders.freeze
+        end
+
+        def encode(text, nonce: false)
+          encoders.first.encode(text, nonce: nonce)
+        end
+
+        def decode(text, nonce: false)
+          data, encoder = decode_versioned(text, nonce: nonce)
+          raise InvalidError unless encoder
+
+          data
+        end
+
+        # The data and the encoder that decoded it, or `[nil, nil]`, so the app can treat old values differently.
+        def decode_versioned(text, nonce: false)
+          encoders.each do |encoder|
+            data = encoder.decode(text, nonce: nonce)
+            return [data, encoder] if data.is_a?(String)
+          rescue ConfigurationError
+            raise
+          rescue StandardError
+            next
+          end
+          [nil, nil]
+        end
+
+        private
+
+        # Fails at boot for a member that would otherwise refuse every value at request time.
+        def check(encoder)
+          unless %i[encode decode].all? { |name| encoder.respond_to?(name) }
+            raise ConfigurationError, "#{encoder.inspect} cannot be versioned: it must respond to encode and decode"
+          end
+          unless %i[encode decode].all? { |name| accepts_nonce?(encoder.method(name)) }
+            raise ConfigurationError, "#{encoder.inspect} cannot be versioned: encode and decode must accept `nonce:`"
+          end
+          return unless encoder.respond_to?(:key) && encoder.respond_to?(:tag) && encoder.key.nil?
+
+          raise ConfigurationError, "#{encoder.inspect} cannot be versioned: it has no key"
+        end
+
+        def accepts_nonce?(method)
+          method.parameters.any? { |kind, name| kind == :keyrest || (%i[key keyreq].include?(kind) && name == :nonce) }
+        end
+      end
+
+      def self.versioned(*encoders)
+        Versioned.new(encoders)
+      end
+    end
+  end
+end

data/lib/graphql/armory/encoder.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module GraphQL
+  module Armory
+    # Encrypts and authenticates IDs and cursors with AES-256-GCM. Subclass it and set a key:
+    #
+    #   class AppEncoder < GraphQL::Armory::Encoder
+    #     key ENV.fetch("GRAPHQL_ARMORY_KEY")
+    #   end
+    #
+    # Cursors (`nonce: true`, as graphql-ruby's connections ask) get a random nonce, so the same position
+    # never gives the same cursor. IDs must be stable, so their nonce is derived from the ID itself with an
+    # HMAC: the same ID always encrypts the same way, and two different IDs never share a nonce.
+    # IDs and cursors use separate keys, so one is never accepted as the other.
+    class Encoder
+      # Raised for anything that does not decode: tampered, foreign, malformed. The message never says which.
+      class InvalidError < GraphQL::ExecutionError
+        def initialize(message = "Invalid ID or cursor")
+          super
+        end
+      end
+
+      class ConfigurationError < Armory::Error; end
+
+      # graphql-ruby's default text form for cursors: base64url without padding.
+      module URLSafeBase64
+        def self.encode(bytes)
+          Base64.urlsafe_encode64(bytes, padding: false)
+        end
+
+        def self.decode(text)
+          Base64.urlsafe_decode64(text)
+        end
+      end
+
+      MINIMUM_KEY_BYTES = 32
+      NONCE_BYTES = 12
+      AUTH_TAG_BYTES = 16
+      CIPHER = "aes-256-gcm"
+
+      class << self
+        # The key, at least 32 bytes. With no argument, answers it (inherited from the parent class).
+        def key(*value)
+          return setting(:@key, nil) if value.empty?
+
+          secret = value.first
+          unless secret.is_a?(String) && secret.bytesize >= MINIMUM_KEY_BYTES
+            raise ConfigurationError, "an Encoder key must be a String of at least #{MINIMUM_KEY_BYTES} bytes (try SecureRandom.hex(32))"
+          end
+
+          @key = secret
+        end
+
+        # Authenticated data: an ID made with another tag does not decode. Use it to separate apps or versions.
+        def tag(*value)
+          return setting(:@tag, "") if value.empty?
+          raise ConfigurationError, "an Encoder tag cannot be nil" if value.first.nil?
+
+          @tag = value.first.to_s
+        end
+
+        # Turns the encrypted bytes into text and back. Anything with `encode(bytes)` and `decode(text)`.
+        def codec(*value)
+          return setting(:@codec, URLSafeBase64) if value.empty?
+          raise ConfigurationError, "an Encoder codec must respond to encode and decode" unless %i[encode decode].all? { |name| value.first.respond_to?(name) }
+
+          @codec = value.first
+        end
+
+        def encode(text, nonce: false)
+          purpose = nonce ? :cursor : :id
+          bytes = text.to_s.b
+          iv = nonce ? OpenSSL::Random.random_bytes(NONCE_BYTES) : derived_nonce(bytes)
+          cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+          cipher.key = subkey(purpose, :cipher)
+          cipher.iv = iv
+          cipher.auth_data = tag
+          sealed = cipher.update(bytes) + cipher.final
+          codec.encode(iv + sealed + cipher.auth_tag)
+        end
+
+        def decode(text, nonce: false)
+          purpose = nonce ? :cursor : :id
+          bytes = codec.decode(text.to_s)
+          # One text form only: a base64 variant with other padding bits is not the same ID.
+          raise InvalidError unless codec.encode(bytes) == text.to_s
+          raise InvalidError if bytes.bytesize < NONCE_BYTES + AUTH_TAG_BYTES
+
+          iv = bytes[0, NONCE_BYTES]
+          cipher = OpenSSL::Cipher.new(CIPHER).decrypt
+          cipher.key = subkey(purpose, :cipher)
+          cipher.iv = iv
+          cipher.auth_tag = bytes[-AUTH_TAG_BYTES..]
+          cipher.auth_data = tag
+          plain = cipher.update(bytes[NONCE_BYTES...-AUTH_TAG_BYTES]) + cipher.final
+          # An ID has one valid form only: its nonce must be the one derived from it.
+          raise InvalidError if !nonce && !OpenSSL.fixed_length_secure_compare(iv, derived_nonce(plain))
+
+          plain.force_encoding(Encoding::UTF_8)
+        rescue ConfigurationError
+          raise
+        rescue StandardError
+          # Whatever the codec, OpenSSL or the input raise, the client learns only that it did not decode.
+          raise InvalidError
+        end
+
+        private
+
+        def setting(ivar, default)
+          return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+
+          superclass.respond_to?(:key) ? superclass.send(:setting, ivar, default) : default
+        end
+
+        def derived_nonce(bytes)
+          OpenSSL::HMAC.digest("SHA256", subkey(:id, :nonce), tag.b + "\0".b + bytes)[0, NONCE_BYTES]
+        end
+
+        # Separate keys per purpose and use, derived with HKDF and cached by the secret they come from, so a key
+        # changed later (here or in a parent class) is used at once.
+        def subkey(purpose, use)
+          secret = key or raise ConfigurationError, "#{name || "Encoder"} has no key: call `key` in its class body"
+          @subkeys ||= {}
+          @subkeys[[secret, purpose, use]] ||= OpenSSL::KDF.hkdf(secret, salt: "graphql-armory", info: "#{purpose}/#{use}",
+                                                                         length: 32, hash: "SHA256")
+        end
+      end
+    end
+  end
+end
+
+require "graphql/armory/encoder/versioned"
+require "graphql/armory/encoder/legacy"
+require "graphql/armory/encoder/default"

data/lib/graphql/armory/ids.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    # Encrypted global IDs in one line:
+    #
+    #   class AppSchema < GraphQL::Schema
+    #     use GraphQL::Armory::IDs                         # the default encoder
+    #     use GraphQL::Armory::IDs, encoder: AppEncoder    # or your own
+    #   end
+    #
+    # Defines `id_from_object` (the type name and the record's id, encrypted) and `object_from_id`, which only
+    # honours visible object types that implement Node. A type that
+    # includes the authorization module's Base is looked up inside the user's scope; any other type only through
+    # `find: ->(type, key, context) { ... }`. Every ID that cannot be honoured answers nil, like a missing record.
+    module IDs
+      SEPARATOR = "/"
+
+      def self.use(schema, encoder: nil, find: nil)
+        lookup = Lookup.new(encoder: encoder || Encoder.default, find: find)
+        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
+
+      # Turns records into IDs and IDs back into records.
+      class Lookup
+        attr_reader :encoder, :find
+
+        def initialize(encoder:, find: nil)
+          @encoder = encoder
+          @find = find
+        end
+
+        def id_for(object, type)
+          key = object.id
+          raise Encoder::ConfigurationError, "#{type.graphql_name} object has no id to build a global ID from" if key.nil?
+
+          encoder.encode("#{type.graphql_name}#{SEPARATOR}#{key}")
+        end
+
+        def object_for(id, context)
+          type_name, key = encoder.decode(id).split(SEPARATOR, 2)
+          return nil if key.nil? || key.empty?
+
+          type = visible_type(type_name, context)
+          return nil unless node_type?(type)
+
+          load(type, key, context)
+        rescue Encoder::InvalidError
+          nil
+        end
+
+        private
+
+        # Through the query's own view of the schema: `Schema.get_type(name, context)` does not apply `visible?`
+        # when graphql-ruby runs without `Schema::Visibility`, `context.types` does in both modes.
+        def visible_type(type_name, context)
+          context.respond_to?(:types) ? context.types.type(type_name) : context.schema.get_type(type_name, context)
+        end
+
+        # Only object types that implement Node can have handed out an ID: root types, payloads and introspection
+        # types never did, so an ID naming them is not honoured (and their model is never looked up).
+        def node_type?(type)
+          type.respond_to?(:kind) && type.kind.object? &&
+            type.interfaces.any? { |interface| interface.graphql_name == "Node" }
+        end
+
+        def load(type, key, context)
+          return Authorization::Integration.find(type, nil, key, context) if type.respond_to?(:armory_model)
+
+          find&.call(type, key, context)
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Armory
-    VERSION = "0.1.0.pre"
+    VERSION = "0.1.0.pre3"
   end
 end

data/lib/graphql/armory.rb

@@ -10,4 +10,6 @@ module GraphQL
   end
 end
 
+require "graphql/armory/encoder"
 require "graphql/armory/authorization"
+require "graphql/armory/ids"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: graphql-armory
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre
+  version: 0.1.0.pre3
 platform: ruby
 authors:
 - Israel
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -34,7 +33,6 @@ description: 'Open-source extensions for graphql-ruby built on its public extens
   points. The first module is authorization: deny-by-default coverage, scoped lists
   and connections, IDOR-safe lookups, mutations, interfaces and unions, visibility
   driven by the policy, and a schema audit for CI.'
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -43,6 +41,8 @@ files:
 - LICENSE
 - MIGRATING.md
 - README.md
+- docs/authorization.md
+- docs/encrypted-ids.md
 - lib/graphql-armory.rb
 - lib/graphql/armory.rb
 - lib/graphql/armory/authorization.rb
@@ -65,6 +65,7 @@ files:
 - lib/graphql/armory/authorization/integration/base.rb
 - lib/graphql/armory/authorization/integration/field.rb
 - lib/graphql/armory/authorization/integration/find_by.rb
+- lib/graphql/armory/authorization/integration/input_object.rb
 - lib/graphql/armory/authorization/integration/object.rb
 - lib/graphql/armory/authorization/integration/resolver.rb
 - lib/graphql/armory/authorization/integration/schema.rb
@@ -73,6 +74,11 @@ files:
 - lib/graphql/armory/authorization/rule.rb
 - lib/graphql/armory/authorization/scope.rb
 - lib/graphql/armory/authorization/telemetry.rb
+- lib/graphql/armory/encoder.rb
+- lib/graphql/armory/encoder/default.rb
+- lib/graphql/armory/encoder/legacy.rb
+- lib/graphql/armory/encoder/versioned.rb
+- lib/graphql/armory/ids.rb
 - lib/graphql/armory/version.rb
 - lib/tasks/graphql_armory.rake
 homepage: https://github.com/israelb/graphql-armory
@@ -84,7 +90,6 @@ metadata:
   changelog_uri: https://github.com/israelb/graphql-armory/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/israelb/graphql-armory/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -95,12 +100,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: 'Authorization for graphql-ruby: Pundit and CanCanCan, deny-by-default, with
   a schema audit.'