darrrr 0.0.2

data/lib/github/delegated_account_recovery/recovery_provider.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    class RecoveryProvider
+      include Provider
+      include CryptoHelper
+
+      INTEGER_FIELDS = [:token_max_size]
+      BASE64_FIELDS = [:countersign_pubkeys_secp256r1]
+      URL_FIELDS = [
+        :issuer, :save_token,
+        :recover_account, :privacy_policy
+      ]
+      REQUIRED_FIELDS = URL_FIELDS + INTEGER_FIELDS + BASE64_FIELDS
+
+      attr_accessor(*REQUIRED_FIELDS)
+      attr_accessor :save_token_async_api_iframe # optional
+      attr_accessor :signing_private_key
+      alias :origin :issuer
+
+      # optional field
+      attr_accessor :icon_152px
+
+      # Used to serve content at /.well-known/delegated-account-recovery/configuration
+      def to_h
+        {
+          "issuer" => self.issuer,
+          "countersign-pubkeys-secp256r1" => self.countersign_pubkeys_secp256r1.dup,
+          "token-max-size" => self.token_max_size,
+          "save-token" => self.save_token,
+          "recover-account" => self.recover_account,
+          "save-token-async-api-iframe" => self.save_token_async_api_iframe,
+          "privacy-policy" => self.privacy_policy
+        }
+      end
+
+      # The CryptoHelper defines an `unseal` method that requires us to define
+      # a `unseal_keys` method that will return the set of keys that are valid
+      # when verifying the signature on a sealed key.
+      def unseal_keys
+        countersign_pubkeys_secp256r1
+      end
+
+      # The URL representing the location of the token. Used to initiate a recovery.
+      #
+      # token_id: the shared ID representing a token.
+      def recovery_url(token_id)
+        [self.recover_account, "?token_id=", URI.escape(token_id)].join
+      end
+
+      # Takes a binary representation of a token and signs if for a given
+      # account provider. Do not pass in a RecoveryToken object. The wrapping
+      # data structure is identical to the structure it's wrapping in format.
+      #
+      # token: the to_binary_s or binary representation of the recovery token
+      #
+      # returns a Base64 encoded representation of the countersigned token
+      # and the signature over the token.
+      def countersign_token(token)
+        begin
+          account_provider = RecoveryToken.account_provider_issuer(token)
+        rescue RecoveryTokenSerializationError, UnknownProviderError
+          raise TokenFormatError, "Could not determine provider"
+        end
+
+        counter_recovery_token = RecoveryToken.build(
+          issuer: self,
+          audience: account_provider,
+          type: COUNTERSIGNED_RECOVERY_TOKEN_TYPE
+        )
+
+        counter_recovery_token.data = token
+        seal(counter_recovery_token)
+      end
+
+      # Validate the token according to the processing instructions for the
+      # save-token endpoint.
+      #
+      # Returns a validated token
+      def validate_recovery_token!(token)
+        errors = []
+
+        # 1. Authenticate the User. The exact nature of how the Recovery Provider authenticates the User is beyond the scope of this specification.
+        # handled in before_filter
+
+        # 4. Retrieve the Account Provider configuration as described in Section 2 using the issuer field of the token as the subject.
+        begin
+          account_provider = RecoveryToken.account_provider_issuer(token)
+        rescue RecoveryTokenSerializationError, UnknownProviderError, TokenFormatError => e
+          raise RecoveryTokenError, "Could not determine provider: #{e.message}"
+        end
+
+        # 2. Parse the token.
+        # 3. Validate that the version value is 0.
+        # 5. Validate the signature over the token according to processing rules for the algorithm implied by the version.
+        begin
+          recovery_token = account_provider.unseal(token)
+        rescue CryptoError => e
+          raise RecoveryTokenError.new("Unable to verify signature of token")
+        rescue TokenFormatError => e
+          raise RecoveryTokenError.new(e.message)
+        end
+
+        # 6. Validate that the audience field of the token identifies an origin which the provider considers itself authoritative for. (Often the audience will be same-origin with the Recovery Provider, but other values may be acceptable, e.g. "https://mail.example.com" and "https://social.example.com" may be acceptable audiences for "https://recovery.example.com".)
+        unless self.origin == recovery_token.audience
+          raise RecoveryTokenError.new("Unnacceptable audience")
+        end
+
+        if DateTime.parse(recovery_token.issued_time).utc < (Time.now - CLOCK_SKEW).utc
+          raise RecoveryTokenError.new("Issued at time is too far in the past")
+        end
+
+        recovery_token
+      end
+    end
+  end
+end

data/lib/github/delegated_account_recovery/recovery_token.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Handles binary serialization/deserialization of recovery token data. It does
+# not manage signing/verification of tokens.
+
+module GitHub
+  module DelegatedAccountRecovery
+    class RecoveryToken
+      extend Forwardable
+
+      attr_reader :token_object
+
+      def_delegators :@token_object, :token_id, :issuer, :issued_time, :options,
+        :audience, :binding_data, :data, :version, :to_binary_s, :num_bytes, :data=, :token_type=, :token_type
+
+      BASE64_CHARACTERS = /\A[0-9a-zA-Z+\/=]+\z/
+
+      # Typically, you would not call `new` directly but instead use `build`
+      # and `parse`
+      #
+      # token_object: a RecoveryTokenWriter/RecoveryTokenReader instance
+      def initialize(token_object)
+        @token_object = token_object
+      end
+      private_class_method :new
+
+      def decode
+        Darrrr.encryptor.decrypt(self.data)
+      end
+
+      # A globally known location of the token, used to initiate a recovery
+      def state_url
+        [DelegatedAccountRecovery.recovery_provider(self.audience).recover_account, "id=#{CGI::escape(token_id.to_hex)}"].join("?")
+      end
+
+      class << self
+        # data: the value that will be encrypted by EncryptedData.
+        # recovery_provider: the provider for which we are building the token.
+        # binding_data: a value retrieved from the recovery provider for this
+        # token.
+        #
+        # returns a RecoveryToken.
+        def build(issuer:, audience:, type:)
+          token = RecoveryTokenWriter.new.tap do |token|
+            token.token_id = SecureRandom.random_bytes(16).bytes.to_a
+            token.issuer = issuer.origin
+            token.issued_time = Time.now.utc.iso8601
+            token.options = 0 # when the token-status endpoint is implemented, change this to 1
+            token.audience = audience.origin
+            token.version = DelegatedAccountRecovery::PROTOCOL_VERSION
+            token.token_type = type
+          end
+          new(token)
+        end
+
+        # serialized_data: a binary string representation of a RecoveryToken.
+        #
+        # returns a RecoveryToken.
+        def parse(serialized_data)
+          new RecoveryTokenReader.new.read(serialized_data)
+        rescue IOError => e
+          message = e.message
+          if serialized_data =~ BASE64_CHARACTERS
+            message = "#{message}: did you forget to Base64.strict_decode64 this value?"
+          end
+          raise RecoveryTokenSerializationError, message
+        end
+
+        # Extract a recovery provider from a token based on the token type.
+        #
+        # serialized_data: a binary string representation of a RecoveryToken.
+        #
+        # returns the recovery provider for the coutnersigned token or raises an
+        #   error if the token is a recovery token
+        def recovery_provider_issuer(serialized_data)
+          issuer(serialized_data, DelegatedAccountRecovery::COUNTERSIGNED_RECOVERY_TOKEN_TYPE)
+        end
+
+        # Extract an account provider from a token based on the token type.
+        #
+        # serialized_data: a binary string representation of a RecoveryToken.
+        #
+        # returns the account provider for the recovery token or raises an error
+        #   if the token is a countersigned token
+        def account_provider_issuer(serialized_data)
+          issuer(serialized_data, DelegatedAccountRecovery::RECOVERY_TOKEN_TYPE)
+        end
+
+        # Convenience method to find the issuer of the token
+        #
+        # serialized_data: a binary string representation of a RecoveryToken.
+        #
+        # raises an error if the token is the not the expected type
+        # returns the account provider or recovery provider instance based on the
+        #   token type
+        private def issuer(serialized_data, token_type)
+          parsed_token = parse(serialized_data)
+          raise TokenFormatError, "Token type must be #{token_type}" unless parsed_token.token_type == token_type
+
+          issuer = parsed_token.issuer
+          case token_type
+          when DelegatedAccountRecovery::RECOVERY_TOKEN_TYPE
+            DelegatedAccountRecovery.account_provider(issuer)
+          when DelegatedAccountRecovery::COUNTERSIGNED_RECOVERY_TOKEN_TYPE
+            DelegatedAccountRecovery.recovery_provider(issuer)
+          else
+            raise RecoveryTokenError, "Could not determine provider"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/github/delegated_account_recovery/serialization/recovery_token_reader.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    class RecoveryTokenReader < BinData::Record
+      uint8 :version
+      uint8 :token_type
+      array :token_id, :type => :uint8, :read_until => lambda { index + 1 == DelegatedAccountRecovery::TOKEN_ID_BYTE_LENGTH }
+      uint8 :options
+      uint16be :issuer_length
+      string :issuer, :read_length => :issuer_length
+      uint16be :audience_length
+      string :audience, :read_length => :audience_length
+      uint16be :issued_time_length
+      string :issued_time, :read_length => :issued_time_length
+      uint16be :data_length
+      string :data, :read_length => :data_length
+      uint16be :binding_data_length
+      string :binding_data, :read_length => :binding_data_length
+    end
+  end
+end

data/lib/github/delegated_account_recovery/serialization/recovery_token_writer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module GitHub
+  module DelegatedAccountRecovery
+    class RecoveryTokenWriter < BinData::Record
+      uint8 :version
+      uint8 :token_type
+      array :token_id, :type => :uint8, :initial_length => DelegatedAccountRecovery::TOKEN_ID_BYTE_LENGTH
+      uint8 :options
+      uint16be :issuer_length, :value => lambda { issuer.length }
+      string :issuer
+      uint16be :audience_length, :value => lambda { audience.length }
+      string :audience
+      uint16be :issued_time_length, :value => lambda { issued_time.length }
+      string :issued_time
+      uint16be :data_length, :value => lambda { data.length }
+      string :data
+      uint16be :binding_data_length, :value => lambda { binding_data.length }
+      string :binding_data
+    end
+  end
+end

data/lib/github/delegated_account_recovery/version.rb

@@ -0,0 +1,5 @@
+module GitHub
+  module DelegatedAccountRecovery
+    VERSION = "0.0.2"
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: darrrr
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Neil Matatall
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-04-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bindata
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: See https://www.facebook.com/notes/protect-the-graph/improving-account-security-with-delegated-recovery/1833022090271267/
+email: opensource+darrrr@github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/darrrr.rb
+- lib/github/delegated_account_recovery.rb
+- lib/github/delegated_account_recovery/account_provider.rb
+- lib/github/delegated_account_recovery/constants.rb
+- lib/github/delegated_account_recovery/crypto_helper.rb
+- lib/github/delegated_account_recovery/cryptors/default/default_encryptor.rb
+- lib/github/delegated_account_recovery/cryptors/default/encrypted_data.rb
+- lib/github/delegated_account_recovery/cryptors/default/encrypted_data_io.rb
+- lib/github/delegated_account_recovery/provider.rb
+- lib/github/delegated_account_recovery/recovery_provider.rb
+- lib/github/delegated_account_recovery/recovery_token.rb
+- lib/github/delegated_account_recovery/serialization/recovery_token_reader.rb
+- lib/github/delegated_account_recovery/serialization/recovery_token_writer.rb
+- lib/github/delegated_account_recovery/version.rb
+homepage: http://github.com/oreoshake/darrrr
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Client library for the Delegated Recovery spec
+test_files: []