app_identity 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30f775dedcf26d6e5951cc7af9440ee560a76529946610300284bdc727d17972
+  data.tar.gz: 1017621f7d5474e23e8823a3d568b3dca11baef8e42a8f43441512205ab54620
+SHA512:
+  metadata.gz: 5f2a942c09c6aa58a25c97552659d7848c2eea717bc94a752b28812ca951234931ad4e233abb7e765b5ce7b5b9574fe050e314ed69a0083fd18cdbe707f9dc9d
+  data.tar.gz: 7b38ec69bad5c20c2360495267944c9172f61475df4cfb8413c241b9c4a821f09ecf1a33a09b6f2a49156ee28a5882af83b630b20e055693e70d5084d277f311

data/.rdoc_options

@@ -0,0 +1,28 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- "."
+charset: UTF-8
+exclude:
+- Manifest.txt\z
+- ~\z
+- \.orig\z
+- \.rej\z
+- \.bak\z
+- \.gemspec\z
+hyperlink_all: false
+line_numbers: false
+locale:
+locale_dir: locale
+locale_name:
+main_page:
+markup: markdown
+output_decoration: true
+page_dir:
+show_hash: false
+tab_width: 8
+template_stylesheets: []
+title:
+visibility: :protected
+webcvs:

data/Changelog.md

@@ -0,0 +1,5 @@
+# App Identity for Ruby Changelog
+
+## 1.0.0 / 2022-09-07
+
+- Initial release.

data/Contributing.md

@@ -0,0 +1,70 @@
+# Contributing
+
+We value contributions to AppIdentity for Ruby—bug reports, discussions, feature
+requests, and code contributions. New features should be proposed and
+[discussed][] prior to implementation, and release of any new feature may be
+delayed until implemented in the three reference implementations.
+
+Before contributing patches, please read the [Licence.md](licence.md).
+
+App Identity is governed under the Kinetic Commerce Open Source [Code of
+Conduct][].
+
+## Code Guidelines
+
+Our usual code contribution guidelines apply:
+
+- Code changes _will not_ be accepted without tests. The test suite is written
+  with [minitest][].
+- Match our coding style. We use [standard Ruby][] to assist with this.
+- Use a thoughtfully-named topic branch that contains your change. Rebase your
+  commits into logical chunks as necessary.
+- Use [quality commit messages][].
+- Certain things must not be changed except as part of the release process. These
+  are:
+  - the version number in `lib/app_identity.rb`
+  - `Gemfile` (this is a stub file)
+  - `app_identity.gemspec` (this is a generated file)
+- Submit a pull request with your changes.
+- New or changed behaviours require new or updated documentation.
+- New dependencies are discouraged.
+
+There are code quality checks performed in GitHub Actions that must pass for any
+pull request to be accepted.
+
+## Test Dependencies
+
+`app_identity` uses Ryan Davis’s [Hoe][] to manage the release process, and it
+adds a number of useful rake tasks.
+
+```console
+$ rake
+Run options: --seed 45847
+
+# Running:
+
+..............................
+
+Finished in 0.005884s, 5098.5724 runs/s, 10197.1448 assertions/s.
+
+30 runs, 60 assertions, 0 failures, 0 errors, 0 skips
+rm -rf doc
+rm -r pkg
+```
+
+We have provided the simplest possible Gemfile pointing to the (generated)
+`app_identity.gemspec` file. This will permit you to use `bundle install` to get
+the development dependencies.
+
+```console
+$ bundle install
+…
+Bundle complete!
+```
+
+[code of conduct]: https://github.com/KineticCafe/code-of-conduct
+[discussed]: https://github.com/KineticCafe/app_identity/discussions
+[hoe]: https://github.com/seattlerb/hoe
+[minitest]: https://github.com/seattlerb/minitest
+[quality commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[standard ruby]: https://github.com/testdouble/standard

data/Licence.md

@@ -0,0 +1,25 @@
+# Licence
+
+App Identity for Ruby is copyright © 2022 Kinetic Commerce and contributors
+and is licensed under [Apache Licence, version 2.0][apache-licence-20].
+
+## Developer Certificate of Origin
+
+All contributors **must** certify they are able and willing to provide their
+contributions under the terms of this project's licenses with the certification
+of the [Developer Certificate of Origin (Version 1.1)][dco].
+
+Such certification is provided by ensuring that the following line must be
+included as the last line of a commit message for every commit contributed:
+
+    Signed-off-by: FirstName LastName <email@example.org>
+
+The `Signed-off-by` line can be automatically added by git with the `-s` or
+`--signoff` option on `git commit`:
+
+```sh
+git commit --signoff
+```
+
+[apache-licence-20]: licences/APAHCE-2.0.txt
+[dco]: licenses/dco.txt

data/Manifest.txt

@@ -0,0 +1,30 @@
+.rdoc_options
+Changelog.md
+Contributing.md
+Licence.md
+Manifest.txt
+README.md
+Rakefile
+bin/app-identity-suite-ruby
+lib/app_identity.rb
+lib/app_identity/app.rb
+lib/app_identity/error.rb
+lib/app_identity/faraday_middleware.rb
+lib/app_identity/internal.rb
+lib/app_identity/rack_middleware.rb
+lib/app_identity/validation.rb
+lib/app_identity/versions.rb
+licences/APACHE-2.0.txt
+licences/DCO.txt
+spec.md
+support/app_identity/suite.rb
+support/app_identity/suite/generator.rb
+support/app_identity/suite/optional.json
+support/app_identity/suite/program.rb
+support/app_identity/suite/required.json
+support/app_identity/suite/runner.rb
+support/app_identity/support.rb
+test/minitest_helper.rb
+test/test_app_identity.rb
+test/test_app_identity_app.rb
+test/test_app_identity_rack_middleware.rb

data/README.md

@@ -0,0 +1,70 @@
+# AppIdentity for Ruby
+
+- code :: https://github.com/KineticCafe/app-identity/tree/main/ruby/
+- issues :: https://github.com/KineticCafe/app-identity/issues
+
+## Description
+
+AppIdentity is a Ruby implementation of the Kinetic Commerce application
+identity proof algorithm as described in its [spec][].
+
+## Synopsis
+
+```ruby
+app = AppIdentity::App.new(id: id, secret: secret, version: 2)
+proof = AppIdentity.generate_proof!(app)
+AppIdentity.verify_proof!(proof, app)
+```
+
+In a Rails application, proof verification would use
+`AppIdentity::RackMiddleware.`
+
+```ruby
+require 'app_identity/rack_middleware'
+
+config.middleware.use AppIdentity::RackMiddleware,
+  header: "app-identity-proof",
+  finder: ->(proof) { IdentityApplication.find(proof[:id]) }
+```
+
+There is a Faraday Middleware for providing proof generation for clients.
+
+```ruby
+Faraday.new(url: url) do |conn|
+  conn.request :app_identity,dentity_app: app,
+    header: 'app-proof-identity'
+end
+```
+
+## Installation
+
+Add `app_identity` to your Gemfile:
+
+```ruby
+gem 'app_identity', '~> 1.0'
+```
+
+## Semantic Versioning
+
+`AppIdentity` uses a [Semantic Versioning][] scheme with one significant change:
+
+- When PATCH is zero (`0`), it will be omitted from version references.
+
+Additionally, the major version will generally be reserved for specification
+revisions.
+
+## Contributing
+
+AppIdentity for Ruby [welcomes contributions](Contributing.md). This project,
+all Kinetic Commerce [open source projects][], is under the Kinetic Commerce
+Open Source [Code of Conduct][kccoc].
+
+AppIdentity for Ruby is licensed under the Apache Licence, version 2.0 and
+requires certification via a Developer Certificate of Origin. See
+[Licence.md](Licence.md) for more details.
+
+[contributing]: Contributing.md
+[kccoc]: https://github.com/KineticCafe/code-of-conduct
+[open source projects]: https://github.com/KineticCafe
+[semantic versioning]: http://semver.org/
+[spec]: https://github.com/KineticCafe/app-identity/blob/main/spec/README.md

data/Rakefile

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "hoe"
+require "rake/clean"
+
+Hoe.plugin :doofus
+Hoe.plugin :gemspec2
+Hoe.plugin :git2
+Hoe.plugin :minitest
+
+Hoe.spec "app_identity" do
+  developer("Austin Ziegler", "aziegler@kineticcommerce.com")
+  developer("Kinetic Commerce", "dev@kineticcommerce.com")
+
+  self.history_file = "Changelog.md"
+  self.readme_file = "README.md"
+
+  license "MIT"
+
+  spec_extras[:metadata] = ->(val) { val["rubygems_mfa_required"] = "true" }
+
+  extra_deps << ["optimist", "~> 3.0"]
+  extra_dev_deps << ["hoe-doofus", "~> 1.0"]
+  extra_dev_deps << ["hoe-gemspec2", "~> 1.1"]
+  extra_dev_deps << ["hoe-git2", "~> 1.7"]
+  extra_dev_deps << ["minitest", "~> 5.4"]
+  extra_dev_deps << ["minitest-autotest", "~> 1.0"]
+  extra_dev_deps << ["minitest-bisect", "~> 1.2"]
+  extra_dev_deps << ["minitest-focus", "~> 1.1"]
+  extra_dev_deps << ["minitest-pretty_diff", "~> 0.1"]
+  extra_dev_deps << ["rack-test", "~> 0.6"]
+  extra_dev_deps << ["rake", ">= 10.0", "< 14.0"]
+  extra_dev_deps << ["rdoc", "~> 6.4"]
+  extra_dev_deps << ["simplecov", "~> 0.7"]
+  extra_dev_deps << ["standard", "~> 1.0"]
+end
+
+namespace :console do
+  task :pry do
+    exec "pry -Ilib -rapp_identity"
+  end
+
+  task :irb do
+    exec "irb -Ilib -rapp_identity"
+  end
+end
+
+desc "Open a console with AppIdentity loaded"
+task console: "console:irb"

data/bin/app-identity-suite-ruby

@@ -0,0 +1,12 @@
+#! /usr/bin/env ruby
+
+root = File.expand_path("../../", __FILE__)
+
+if File.exist?(File.join(root, "app_identity.gemspec"))
+  $LOAD_PATH.unshift(File.join(root, "lib"), File.join(root, "support"))
+end
+
+require "optimist"
+require "app_identity/suite"
+
+exit 1 unless AppIdentity::Suite::Program.run(name: File.basename(__FILE__))

data/lib/app_identity/app.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+require_relative "error"
+require_relative "validation"
+
+# The class used by the App Identity proof generation and verification
+# algorithms. This will typically be constructed from another object, structure,
+# or hash, such as from a static configuration file or a database record.
+#
+# AppIdentity::App objects are created frozen, and certain operations may
+# provide a modified duplicate.
+class AppIdentity::App
+  def self.new(input) # :nodoc:
+    if input.is_a?(AppIdentity::App) && !input.verified
+      input
+    else
+      super
+    end
+  end
+
+  include AppIdentity::Validation
+
+  # The AppIdentity App unique identifier. Validation of the `id` value will
+  # convert non-string IDs using #to_s.
+  #
+  # If using integer IDs, it is recommended that the `id` value be provided as
+  # some form of extended string value, such as that provided by Rails [global
+  # ID](https://github.com/rails/globalid). Such representations are _also_
+  # recommended if the ID is a compound value.
+  #
+  # `id` values _must not_ contain a colon (`:`) character.
+  attr_reader :id
+
+  # The App Identity app secret value. This value is used _as provided_ with no
+  # encoding or decoding. As this is a sensitive value, it may be provided
+  # as a 0-arity closure proc.
+  #
+  # For security purposes, this is always stored as a 0-arity closure proc.
+  attr_reader :secret
+
+  # The positive integer version of the AppIdentity algorithm to use. Will be
+  # validated to be a supported version for app creation, and not an explicitly
+  # disallowed version during proof validation.
+  #
+  # A string `version` must convert cleanly to an integer value, meaning that
+  # `"3.5"` is not a valid value.
+  #
+  # AppIdentity algorithm versions are strictly upgradeable. That is, a version
+  # 1 app can verify version 1, 2, 3, or 4 proofs. However, a version 2 app will
+  # _never_ validate a version 1 proof.
+  #
+  # <table>
+  #   <thead>
+  #     <tr>
+  #       <th rowspan=2>Version</th>
+  #       <th rowspan=2>Nonce</th>
+  #       <th rowspan=2>Digest Algorithm</th>
+  #       <th colspan=4>Can Verify</th>
+  #     </tr>
+  #     <tr><th>1</th><th>2</th><th>3</th><th>4</th></tr>
+  #   </thead>
+  #   <tbody>
+  #     <tr><th>1</th><td>random</td><td>SHA 256</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
+  #     <tr><th>2</th><td>timestamp ± fuzz</td><td>SHA 256</td><td>⛔️</td><td>✅</td><td>✅</td><td>✅</td></tr>
+  #     <tr><th>3</th><td>timestamp ± fuzz</td><td>SHA 384</td><td>⛔️</td><td>⛔️</td><td>✅</td><td>✅</td></tr>
+  #     <tr><th>4</th><td>timestamp ± fuzz</td><td>SHA 512</td><td>⛔️</td><td>⛔️</td><td>⛔️</td><td>✅</td></tr>
+  #   </tbody>
+  # </table>
+  attr_reader :version
+
+  # An optional configuration value for validation of an App Identity proof.
+  #
+  # If not provided, the default value when required is `{fuzz: 600}`,
+  # specifying that the timestamp may not differ from the current time by more
+  # than ±600 seconds (±10 minutes). Depending on the nature of the app being
+  # verified and the expected network conditions, a shorter time period than 600
+  # seconds is recommended.
+  #
+  # The App Identity version 1 algorithm does not use `config`.
+  attr_reader :config
+
+  # The original object used to construct this App Identity object.
+  attr_reader :source
+
+  # Whether this app was used in the successful verification of a proof.
+  attr_reader :verified
+
+  # Constructs an AppIdentity::App from a provided object or zero-arity
+  # callable that returns an initialization object. These values should be
+  # treated as immutable objects.
+  #
+  # The object must respond to `#id`, `#secret`, `#version`, and `#config` or
+  # have indexable keys (via `#[]`) of `id`, `secret`, `version`, and `config`
+  # as either Symbol or String values. That is, the `id` should be retrievable
+  # in one of the following ways:
+  #
+  # ```ruby
+  # input.id
+  # input[:id]
+  # input["id"]
+  # ```
+  #
+  # If the input parameter is a callable, it will be called with no
+  # parameters to produce an input object.
+  #
+  # The AppIdentity::App is frozen on creation.
+  #
+  # ```ruby
+  # AppIdentity::App.new({id: 1, secret: "secret", version: 1})
+  #
+  # AppIdentity::App.new(->() { {id: 1, secret: "secret", version: 1} })
+  # ```
+  #
+  # If the provided `input` is already an App and is not #verified, the existing
+  # app will be returned instead of creating a new application.
+  def initialize(input)
+    input = input.call if input.respond_to?(:call)
+
+    @id = get(input, :id)
+    @secret = fwrap(get(input, :secret).dup)
+    @version = get(input, :version)
+    @config = get(input, :config)
+    @source = input
+    @verified = false
+
+    validate!
+    freeze
+  end
+
+  # If the current App is not `verified`, then return a copy of the current App
+  # with the verified flag set to `true`.
+  def verify
+    verified ? self : dup.tap { |v| v.instance_variable_set(:@verified, true) }.freeze
+  end
+
+  # If the current App is `verified`, then return a copy of the current App
+  # with the verified flag set to `false`.
+  def unverify
+    verified ? dup.tap { |v| v.instance_variable_set(:@verified, false) }.freeze : self
+  end
+
+  # Generate a nonce for this application. Optionally provide a version number
+  # override to generate a compatible (upgraded) nonce version.
+  def generate_nonce(version = nil)
+    version ||= self.version
+
+    unless self.version <= version
+      raise "app version #{self.version} is not compatible with requested version #{version}"
+    end
+
+    AppIdentity::Versions[version].generate_nonce
+  end
+
+  def to_h # :nodoc:
+    {config: config, id: id, secret: secret.call, version: version}
+  end
+
+  alias_method :as_json, :to_h
+
+  def to_s # :nodoc:
+    inspect
+  end
+
+  def to_json(*args, **kwargs) # :nodoc:
+    as_json.to_json(*args, **kwargs)
+  end
+
+  def hash # :nodoc:
+    [AppIdentityApp::App, id, version, config, secret]
+  end
+
+  def inspect # :nodoc:
+    "#<#{self.class} id: #{id} version: #{version} config: #{config} verified: #{verified}>"
+  end
+
+  def ==(other) # :nodoc:
+    other.is_a?(self.class) &&
+      id == other.id &&
+      version == other.version &&
+      config == other.config &&
+      verified == other.verified &&
+      secret.call == other.secret.call
+  end
+
+  private
+
+  def get(input, key)
+    case input
+    when Hash, Struct, OpenStruct
+      input[key] || input[key.to_s]
+    else
+      if input.respond_to?(key)
+        input.__send__(key)
+      elsif input.respond_to?(:[]) && !input.is_a?(Array)
+        input[key] || input[key.to_s]
+      else
+        raise AppIdentity::Error, "app cannot be created from input (missing value #{key.inspect})"
+      end
+    end
+  end
+
+  def fwrap(value)
+    value.respond_to?(:call) ? value : -> { value }
+  end
+
+  def validate!
+    @id = validate_id(@id)
+    @secret = fwrap(validate_secret(@secret))
+    @version = validate_version(@version)
+    @config = validate_config(@config)
+  end
+end

data/lib/app_identity/error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# An exception that will be raised by AppIdentity.generate_proof!,
+# AppIdentity.parse_proof!, or AppIdentity.verify_proof! when those functions
+# fail. The error message reported here is *always* generic.
+#
+# This can also be raised by AppIdentity::RackMiddleware on configuration
+# failure.
+class AppIdentity::Error < ::StandardError
+  attr_reader :message # :nodoc:
+
+  def initialize(type) # :nodoc:
+    @message = resolve(type)
+  end
+
+  private
+
+  def resolve(type)
+    case type
+    when String
+      type
+    when :verify_proof
+      "Error verifying proof"
+    when :generate_proof
+      "Error generating proof"
+    when :parse_proof
+      "Error parsing proof"
+    when :disallowed_configuration_error
+      "error in disallowed version configuration"
+    when :plug_missing_apps_or_finder
+      "AppIdentity::RackMiddleware configuration error: one of `apps` or `finder` options is required"
+    when :plug_headers_required
+      "AppIdentity::RackMiddleware configuration error: `headers` option is required"
+    when :plug_header_invalid
+      "AppIdentity::RackMiddleware configuration error: `headers` value is invalid"
+    when :plug_on_failure_invalid
+      "AppIdentity::RackMiddleware configuration error: `on_failure` value is invalid"
+    when :plug_disallowed_invalid
+      "AppIdentity::RackMiddleware configuration error: `disallowed` value is invalid"
+    end
+  end
+end

data/lib/app_identity/faraday_middleware.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+if defined?(Faraday::Middleware)
+  require "app_identity"
+
+  # A Faraday middleware that generates an app identity proof header for
+  # a request.
+  #
+  # The `options` provided has the following parameters:
+  #
+  # - `app`: (required) An AppIdentity::App or object that can be coerced into
+  #   an AppIdentity::app with AppIdentity#new.
+  #
+  # - `disallowed`: A list of algorithm versions that are not allowed when
+  #   processing received identity proofs. See AppIdentity::Versions.allowed?.
+  #
+  # - `header`: (required) The header to use for sending the app identity proof.
+  #
+  # - `on_failure`: (optional) The action to take when an app identity proof
+  #   cannot be generated for any reason. May be one of the following values:
+  #
+  #     - `:fail`: Throws an exception. This is the default if `on_failure` is
+  #       not specified.
+  #
+  #     - `:pass`: Sets the header to the empty value returned. The request will
+  #       probably fail on the receiving server side.
+  #
+  #     - `:skip`: Does not add the header, as if the request were not made
+  #       using an application.
+  #
+  # `on_failure` may also be provided a callable object that expects three
+  # parameters:
+  #
+  # - `env`: The Faraday middleware `env` value;
+  # - `app`: The identity app value provided to the middleware; and
+  # - `header`: The header name provided to the middleware.
+  #
+  # The callable may return either the `env`, `:fail`, `:skip`, or `:pass`. Any
+  # other value will be treated as `:fail`.
+  class AppIdentity::FaradayMiddleware < Faraday::Middleware
+    def initialize(app, options = {}) # :nodoc:
+      super(app)
+
+      @identity_app = AppIdentity::App.new(options.fetch(:app))
+      @header = options.fetch(:header).downcase
+      @on_failure = options.fetch(:on_failure, :fail)
+      @disallowed = options.fetch(:disallowed, nil)
+    end
+
+    def call(env) # :nodoc:
+      proof = AppIdentity.generate_proof(@identity_app, disallowed: @disallowed)
+
+      if proof.nil?
+        handle_failure(@on_failure)
+      else
+        env[:request_headers][@header] = proof
+      end
+
+      @app.call(env)
+    end
+
+    private
+
+    def handle_failure(on_failure)
+      case on_failure
+      when :skip
+        nil
+      when :pass
+        env[:request_headers][@header] = ""
+      when :fail
+        raise AppIdentity::Error, "unable to generate proof for app #{@identity_app.id}"
+      else
+        if on_failure.respond_to?(:call)
+          result = on_failure.call(env, @identity_app, @header)
+
+          case result
+          when :skip, :pass, :fail
+            return handle_failure(result)
+          else
+            if result.eql?(env)
+              return
+            else
+              return handle_failure(:fail)
+            end
+          end
+        end
+
+        handle_failure(:fail)
+      end
+    end
+  end
+
+  Faraday::Request.register_middleware app_identity: -> { AppIdentity::FaradayMiddleware }
+end