app_identity 1.0.0

data/lib/app_identity/internal.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "validation"
+require_relative "versions"
+
+class AppIdentity::Internal # :nodoc:
+  include AppIdentity::Validation
+
+  class << self
+    private :new
+
+    def instance
+      @instance ||= new
+    end
+
+    def generate_proof!(app, **kwargs)
+      instance.generate_proof!(app, **kwargs)
+    end
+
+    def parse_proof!(proof)
+      instance.parse_proof!(proof)
+    end
+
+    def verify_proof!(proof, app, **kwargs)
+      instance.verify_proof!(proof, app, **kwargs)
+    end
+  end
+
+  def generate_proof!(app, nonce: nil, version: nil, disallowed: nil)
+    app = AppIdentity::App.new(app)
+    version ||= app.version
+    nonce ||= app.generate_nonce(version)
+
+    __generate_proof(app, nonce, version, disallowed: disallowed)
+  end
+
+  def parse_proof!(proof)
+    return proof if proof.is_a?(Hash)
+
+    raise AppIdentity::Error, "proof must be a string or a map" unless proof.is_a?(String)
+
+    parts = Base64.decode64(proof).split(":", -1)
+
+    case parts.length
+    when 4
+      version, id, nonce, padlock = parts
+
+      version = validate_version(version)
+      AppIdentity::Versions.allowed!(version)
+
+      {version: version, id: id, nonce: nonce, padlock: padlock}
+    when 3
+      id, nonce, padlock = parts
+
+      {version: 1, id: id, nonce: nonce, padlock: padlock}
+    else
+      raise AppIdentity::Error, "proof must have 3 parts (version 1) or 4 parts (any version)"
+    end
+  end
+
+  def verify_proof!(proof, app, disallowed: nil)
+    proof = parse_proof!(proof)
+
+    app = app.call(proof) if app.respond_to?(:call)
+    app = AppIdentity::App.new(app)
+
+    raise AppIdentity::Error, "proof and app do not match" unless app.id == proof[:id]
+    raise AppIdentity::Error, "proof and app version mismatch" if app.version > proof[:version]
+    AppIdentity::Versions.allowed!(proof[:version], disallowed)
+
+    valid_nonce!(proof[:nonce], proof[:version], app.config)
+    validate_padlock(proof[:padlock])
+
+    padlock = __generate_padlock(app, proof[:nonce], proof[:version])
+
+    compare_padlocks(padlock, proof[:padlock]) ? app.verify : nil
+  end
+
+  private
+
+  def __generate_proof(app, nonce, version, disallowed: nil)
+    AppIdentity::Versions.allowed!(version, disallowed)
+
+    padlock = __generate_padlock(app, nonce, version)
+
+    return unless padlock
+
+    parts =
+      case version
+      when 1
+        [app.id, nonce, padlock]
+      else
+        [version, app.id, nonce, padlock]
+      end
+
+    Base64.urlsafe_encode64(parts.join(":"))
+  end
+
+  def __generate_padlock(app, nonce, version)
+    versions_compatible!(app.version, version)
+    valid_nonce!(nonce, version, app.config)
+    AppIdentity::Versions[version].make_digest([app.id, nonce, app.secret.call].join(":"))
+  end
+
+  def versions_compatible!(app_version, version)
+    return if app_version <= version
+    raise AppIdentity::Error, "app version #{app_version} is not compatible with proof version #{version}"
+  end
+
+  def valid_nonce!(nonce, version, config)
+    AppIdentity::Versions[version].check_nonce!(nonce, config)
+  end
+
+  def compare_padlocks(generated, provided)
+    return false if generated.nil? || generated.empty?
+    return false if provided.nil? || provided.empty?
+    return false if generated.length != provided.length
+
+    generated = generated.upcase.unpack("C*")
+    provided = provided.upcase.unpack("C*")
+
+    generated.zip(provided).map { |a, b| a ^ b }.reduce(:+) == 0
+  end
+
+  def generate_version_nonce(version)
+    version = validate_version(version)
+    AppIdentity[validate_version(version)][:nonce].call
+  end
+end

data/lib/app_identity/rack_middleware.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "rack"
+require "app_identity"
+require "app_identity/error"
+require "set"
+
+# A Rack middleware that verifies App Identity proofs provided via one or more
+# HTTP headers.
+#
+# When multiple proof values are provided in the request, all must be
+# successfully verified. If any of the proof values cannot be verified, request
+# processing halts with `403 Forbidden`. Should no proof headers are included,
+# the request is considered invalid.
+#
+# All of the above behaviours can be modified through configuration (see below).
+#
+# The results of completed proof validations can be found at
+# env["app_identity"], regardless of success or failure.
+#
+# ### Configuration
+#
+# The Rack middlware can be configured with the following options:
+#
+# - `apps`: A list of AppIdentity::App objects or objects that can be converted
+#   into AppIdentity::App objects to be used for proof validation. Duplicate
+#   values will be ignored.
+#
+# - `disallowed`: A list of algorithm versions that are not allowed when
+#   processing received identity proofs. See AppIdentity::Versions.allowed?.
+#
+# - `finder`: A 1-arity callable function that will load an input to
+#   AppIdentity::App.new from an external source given a parsed proof.
+#
+# - `headers`: A list of HTTP header names.
+#
+# - `on_failure`: The behaviour of the Rack middleware when proof validation
+#   fails. Must be one of the following values:
+#
+#     - `:forbidden`: Halt request processing and respond with a `403`
+#       (forbidden) status. This is the same as `[:halt, :forbidden]`. This is
+#       the default `on_failure` behaviour.
+#
+#     - `[:halt, status]`: Halt request processing and return the specified
+#       status code. An empty body is emitted.
+#
+#     - `[:halt, status, body]`: Halt request processing and return the
+#       specified status code. The body value is included in the response.
+#
+#     - `:continue`: Continue processing, ensuring that failure states are
+#       recorded for the application to act on at a later point. This could be
+#       used to implement a distinction between *validating* a proof and
+#       *requiring* that the proof is valid.
+#
+#     - A 1-arity callable accepting the Rack `env` value and returns one of the
+#       above values.
+#
+# At least one of `apps` or `finder` **must** be supplied. If both are present,
+# apps are looked up in the `apps` list first.
+#
+# ```ruby
+# use AppIdentity::RackMiddleware, header: "application-identity",
+#   finder: ->(proof) { ApplicationModel.find(proof[:id]) }
+# ```
+class AppIdentity::RackMiddleware
+  def initialize(app, options = {}) # :nodoc:
+    @app = app
+
+    if !options.has_key?(:apps) && !options.has_key?(:finder)
+      raise AppIdentity::Error, :plug_missing_apps_or_finder
+    end
+
+    @apps = get_apps(options)
+    @finder = options[:finder]
+
+    if @apps.empty? && @finder.nil?
+      raise "One of `apps` or `finder` options is required."
+    end
+
+    @disallowed = get_disallowed(options)
+    @headers = get_headers(options)
+    @on_failure = get_on_failure(options)
+  end
+
+  def call(env) # :nodoc:
+    headers = verify_headers(Hash[*@headers.flat_map { |h| [h, env[h]] }])
+
+    env["app_identity"] = headers
+
+    if has_errors?(headers)
+      dispatch_on_failure(@on_failure, env)
+    else
+      @app.call(env)
+    end
+  end
+
+  private
+
+  def dispatch_on_failure(on_failure, env)
+    if on_failure.respond_to?(:call)
+      dispatch_on_failure(on_failure.call(env), env)
+    elsif on_failure == :forbidden
+      halt
+    elsif on_failure == :continue
+      @app.call(env)
+    elsif on_failure.is_a?(Array) && on_failure.first == :halt
+      _, status, body = on_failure
+      halt(status, body)
+    end
+  end
+
+  def has_errors?(headers)
+    headers.empty? || headers.any? { |_k, v| v.nil? || v.empty? || v.any? { |vv| vv.nil? || !vv.verified } }
+  end
+
+  def halt(status = nil, body = nil)
+    status ||= :forbidden
+    status = Rack::Utils.status_code(status) if status.is_a?(Symbol)
+
+    body = Array(body)
+
+    length = body.empty? ? "0" : body.length.to_s
+
+    [status, {"Content-Type" => "text/plain", "Content-Length" => length}, body]
+  end
+
+  def verify_headers(headers)
+    headers.each_with_object({}) { |(header, values), result|
+      next if values.nil? || values.empty?
+
+      # If Rack can start returning arrays, we are ready.
+
+      result[header] = Array(values).each_with_object([]) { |value, list|
+        break list if verify_header_value(value, list) == :halt
+      }
+    }
+  end
+
+  def verify_header_value(value, list)
+    proof = AppIdentity.parse_proof(value)
+    return handle_proof_error(list, nil) unless proof
+
+    app = @apps[proof[:id]]
+
+    if app.nil? && @finder
+      app = AppIdentity::App.new(finder.call(proof))
+      @apps[app.id] = app
+    end
+
+    return handle_proof_error(list, nil) unless app
+
+    verified = AppIdentity.verify_proof(proof, app, disallowed: @disallowed)
+
+    if verified
+      list << verified
+      :cont
+    else
+      handle_proof_error(list, verified)
+    end
+  end
+
+  def handle_proof_error(list, value)
+    case @on_failure
+    when :continue
+      list << value
+      :cont
+    when :forbidden, Array
+      :halt
+    else
+      list << value
+      :cont
+    end
+  end
+
+  def get_request_headers(env)
+    Hash[*@headers.lazy.flat_map { |header| [header, env[header]] }]
+  end
+
+  def get_apps(options)
+    options.fetch(:apps, []).each_with_object({}) { |input, map|
+      app = AppIdentity::App.new(input)
+      map[app.id] = app unless map.key?(app.id)
+    }
+  end
+
+  def get_disallowed(options)
+    disallowed = options[:disallowed] || []
+
+    if disallowed.is_a?(Set)
+      disallowed
+    elsif disallowed.is_a?(Array)
+      Set.new(disallowed)
+    else
+      raise AppIdentity::Error, :plug_disallowed_invalid
+    end
+  end
+
+  def get_headers(options)
+    headers = options[:headers] || []
+
+    raise AppIdentity::Error, :plug_headers_required if !headers.is_a?(Array) || headers.empty?
+
+    headers.map { |header| parse_option_header(header) }
+  end
+
+  def get_on_failure(options)
+    resolve_on_failure_option(options[:on_failure] || :forbidden)
+  end
+
+  def parse_option_header(header)
+    if !header.is_a?(String) || header.empty?
+      raise AppIdentity::Error, :plug_header_invalid
+    end
+
+    if /\AHTTP_[A-Z_0-9]+\z/.match?(header)
+      header
+    else
+      -"HTTP_#{header.to_s.tr("-", "_").upcase}"
+    end
+  end
+
+  def resolve_on_failure_option(value)
+    valid =
+      case value
+      when :forbidden, :continue
+        true
+      when Array
+        case [value.first, value.length, value[1].class]
+        when [:halt, 2, Symbol], [:halt, 2, Integer], [:halt, 3, Symbol], [:halt, 3, Integer]
+          true
+        end
+      else
+        value.respond_to?(:call)
+      end
+
+    if valid
+      value
+    else
+      raise AppIdentity::Error, :plug_on_failure_invalid
+    end
+  end
+end

data/lib/app_identity/validation.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+class AppIdentity
+  module Validation # :nodoc:
+    def validate_id(id) # :nodoc:
+      id.tap {
+        validate_not_nil(:id, id)
+        validate_not_empty(:id, id.to_s)
+        validate_no_colons(:id, id.to_s)
+      }.to_s
+    end
+
+    def validate_secret(secret) # :nodoc:
+      secret.tap {
+        secret = secret.call if secret.respond_to?(:call)
+
+        validate_not_nil(:secret, secret)
+        raise AppIdentity::Error, "secret must be a binary string value" unless secret.is_a?(String)
+        validate_not_empty(:secret, secret)
+      }
+    end
+
+    def validate_version(version) # :nodoc:
+      version.tap {
+        validate_not_nil(:version, version)
+
+        begin
+          version = Integer(version) if version.is_a?(String)
+        rescue
+          raise AppIdentity::Error, "version cannot be converted to an integer"
+        end
+
+        if !version.is_a?(Integer) || version <= 0
+          raise AppIdentity::Error, "version must be a positive integer"
+        end
+      }.to_i
+    end
+
+    def validate_config(config) # :nodoc:
+      config.tap {
+        raise AppIdentity::Error, "config must be nil or a map" unless config.nil? || config.is_a?(Hash)
+
+        if config.is_a?(Hash)
+          fuzz = config[:fuzz] || config["fuzz"]
+
+          case fuzz
+          when nil
+            nil
+          when Integer
+            raise AppIdentity::Error, "config.fuzz must be a positive integer or nil" unless fuzz > 0
+          else
+            raise AppIdentity::Error, "config.fuzz must be a positive integer or nil"
+          end
+        end
+      }
+    end
+
+    def validate_padlock(padlock) # :nodoc:
+      padlock.tap {
+        validate_not_nil(:padlock, padlock)
+        raise AppIdentity::Error, "padlock must be a string" unless padlock.is_a?(String)
+        validate_not_empty(:padlock, padlock)
+        validate_no_colons(:padlock, padlock)
+      }
+    end
+
+    private
+
+    def validate_not_nil(type, value)
+      raise AppIdentity::Error, "#{type} must not be nil" if value.nil?
+    end
+
+    def validate_not_empty(type, value)
+      raise AppIdentity::Error, "#{type} must not be an empty string" if value.empty?
+    end
+
+    def validate_no_colons(type, value)
+      raise AppIdentity::Error, "#{type} must not contain colons" if /:/.match?(value)
+    end
+  end
+end

data/lib/app_identity/versions.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "time"
+require "digest/sha2"
+require "securerandom"
+require "set"
+
+require_relative "validation"
+require_relative "error"
+
+class AppIdentity
+  module Versions # :nodoc:
+    class Base # :nodoc:
+      class << self
+        def defined # :nodoc:
+          @defined ||= {}
+        end
+
+        def instance # :nodoc:
+          @_instance = new
+        end
+
+        def inherited(subclass) # :nodoc:
+          match = /V(?<version>\d+)\z/.match(subclass.name)
+          return unless match
+          version = match[:version].to_i
+
+          raise AppIdentity::Error, "version is not unique" if Base.defined.has_key?(version)
+
+          subclass.define_method(:version) { version }
+
+          Base.defined[version] = subclass.instance
+        end
+
+        private :new
+      end
+
+      def make_digest(raw) # :nodoc:
+        digest_algorithm.hexdigest(raw).upcase
+      end
+
+      def inspect # :nodoc:
+        parts = [self.class]
+        parts << "version=#{version}" if respond_to?(:version)
+        parts << "nonce=#{nonce_type}" if respond_to?(:nonce_type)
+        parts << "digest=#{digest_algorithm}" if respond_to?(:digest_algorithm)
+        "#<#{parts.join(" ")}>"
+      end
+
+      def check_nonce!(nonce, _config) # :nodoc:
+        raise AppIdentity::Error, "nonce must not be nil" if nonce.nil?
+        raise AppIdentity::Error, "nonce must be a string" unless nonce.is_a?(String)
+        raise AppIdentity::Error, "nonce must not be blank" if nonce.empty?
+        raise AppIdentity::Error, "nonce must not contain colon characters" if /:/.match?(nonce)
+      end
+    end
+
+    class RandomNonce < Base # :nodoc:
+      def nonce_type # :nodoc:
+        :random
+      end
+
+      def generate_nonce # :nodoc:
+        SecureRandom.urlsafe_base64(32)
+      end
+    end
+
+    class TimestampNonce < Base # :nodoc:
+      def nonce_type # :nodoc:
+        :timestamp
+      end
+
+      def generate_nonce # :nodoc:
+        Time.now.utc.strftime("%Y%m%dT%H%M%S.%6NZ")
+      end
+
+      def check_nonce!(nonce, config) # :nodoc:
+        super(nonce, config)
+
+        timestamp = parse_timestamp!(nonce)
+        config ||= default_config
+        fuzz = config[:fuzz] || config["fuzz"] || 600
+
+        diff = (Time.now.utc - timestamp).abs.to_i
+
+        raise AppIdentity::Error, "nonce is invalid" unless diff <= fuzz
+      end
+
+      private
+
+      def default_config
+        {fuzz: 600}
+      end
+
+      def parse_timestamp!(nonce)
+        Time.strptime(nonce, "%Y%m%dT%H%M%S.%N%Z").tap { |value| raise if value.nil? }.utc
+      rescue
+        raise AppIdentity::Error, "nonce does not look like a timestamp"
+      end
+    end
+
+    # V1 is the original algorithm, using a permanent nonce value and SHA256
+    # digests. The use of this version is strongly discouraged for new clients.
+    class V1 < RandomNonce # :nodoc:
+      def digest_algorithm # :nodoc:
+        Digest::SHA256
+      end
+    end
+
+    # V2 uses a timestamp-based nonce value with SHA256 digests.
+    #
+    # The nonce values will be verified to be within plus or minus a configured
+    # number of seconds.
+    class V2 < TimestampNonce # :nodoc:
+      def digest_algorithm # :nodoc:
+        Digest::SHA256
+      end
+    end
+
+    # V3 uses a timestamp-based nonce value with SHA384 digests.
+    #
+    # The nonce values will be verified to be within plus or minus a configured
+    # number of seconds.
+    class V3 < TimestampNonce # :nodoc:
+      def digest_algorithm # :nodoc:
+        Digest::SHA384
+      end
+    end
+
+    # V4 uses a timestamp-based nonce value with SHA512 digests.
+    #
+    # The nonce values will be verified to be within plus or minus a configured
+    # number of seconds.
+    class V4 < TimestampNonce # :nodoc:
+      def digest_algorithm # :nodoc:
+        Digest::SHA512
+      end
+    end
+
+    class << self
+      include AppIdentity::Validation
+
+      # Looks up the version instance by version.
+      def [](version) # :nodoc:
+        AppIdentity::Versions::Base.defined.fetch(version)
+      end
+
+      # Checks to see if the version has been defined.
+      def valid?(version) # :nodoc:
+        AppIdentity::Versions::Base.defined.has_key?(version)
+      end
+
+      # Tests that the version is valid or raises an exception.
+      def valid!(version) # :nodoc:
+        return true if valid?(version)
+        raise AppIdentity::Error, "version must be one of #{AppIdentity::Versions::Base.defined.keys}"
+      end
+
+      # Checks to see if the version is valid and not explicitly disallowed,
+      # either in the provided list or in global list.
+      def allowed?(version, provided = nil)
+        valid?(version) && !disallowed.member?(version) &&
+          !Set.new(provided).member?(version)
+      end
+
+      # Tests that the version is valid and not explicitly disallowed or raises
+      # an exception.
+      def allowed!(version, provided = nil)
+        return true if valid!(version) && allowed?(version, provided)
+        raise AppIdentity::Error, "version #{version} has been disallowed"
+      end
+
+      # Globally disallow the listed versions.
+      def disallow(*versions)
+        disallowed.merge(coerce_versions(versions))
+      end
+
+      # Globally allow the listed versions.
+      def allow(*versions)
+        disallowed.subtract(coerce_versions(versions))
+      end
+
+      private
+
+      def coerce_versions(versions)
+        versions.select { |v| v.is_a?(Integer) }
+      end
+
+      def disallowed
+        @disalllowed ||= Set.new
+      end
+    end
+  end
+end