darrrr 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b73c12978f19a57c566f6cdc1e3caf2409307b89
+  data.tar.gz: 84ea2347b3d30a53489cfafad46b7aa4d5d4dc13
+SHA512:
+  metadata.gz: 5c224e64fc58c14ee6dc13272274d74f8439d20d73781770b007d13db567dfed10760a739737bf07922e0ac8f04496cac578a4facb58409167329dd3626031f6
+  data.tar.gz: f2800490548b13ae9d5da99bcce76552f508b51975f2cf864427802ed895288c734eae0f30044c8ade4351fe41eacd5af8bf6f1b2b1a1f12e69426d38d3f1fb8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 GitHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+[![Build Status](https://travis-ci.org/github/darrrr.svg?branch=master)](https://travis-ci.org/github/darrrr) [![Code Climate](https://codeclimate.com/github/github/darrrr/badges/gpa.svg)](https://codeclimate.com/github/github/darrrr)
+
+The Delegated Account Recovery Rigid Reusable Ruby (aka D.a.r.r.r.r. or "Darrrr") library is meant to be used as the fully-complete plumbing in your Rack application when implementing the [Delegated Account Recovery specification](https://github.com/facebook/DelegatedRecoverySpecification). This library is currently used for the implementation at [GitHub](https://githubengineering.com/recover-accounts-elsewhere/).
+
+Along with a fully featured library, a proof of concept application is provided in this repo.
+
+## Configuration
+
+An account provider (e.g. GitHub) is someone who stores a token with someone else (a recovery provider e.g. Facebook) in order to grant access to an account.
+
+In `config/initializers` or any location that is run during application setup, add a file:
+
+```ruby
+Darrrr.authority = "http://localhost:9292"
+Darrrr.privacy_policy = "#{Darrrr.authority}/articles/github-privacy-statement/"
+Darrrr.icon_152px = "#{Darrrr.authority}/icon.png"
+
+# See script/setup for instructions on how to generate keys
+Darrrr::AccountProvider.configure do |config|
+  config.signing_private_key = ENV["ACCOUNT_PROVIDER_PRIVATE_KEY"]
+  config.symmetric_key = ENV["TOKEN_DATA_AES_KEY"]
+  config.tokensign_pubkeys_secp256r1 = [ENV["ACCOUNT_PROVIDER_PUBLIC_KEY"]]
+  config.save_token_return = "#{Darrrr.authority}/account-provider/save-token-return"
+  config.recover_account_return = "#{Darrrr.authority}/account-provider/recover-account-return"
+end
+
+Darrrr::RecoveryProvider.configure do |config|
+  config.signing_private_key = ENV["RECOVERY_PROVIDER_PRIVATE_KEY"]
+  config.countersign_pubkeys_secp256r1 = [ENV["RECOVERY_PROVIDER_PUBLIC_KEY"]]
+  config.token_max_size = 8192
+  config.save_token = "#{Darrrr.authority}/recovery-provider/save-token"
+  config.recover_account = "#{Darrrr.authority}/recovery-provider/recover-account"
+end
+```
+
+The delegated recovery spec depends on publicly available endpoints serving standard configs. These responses can be cached but are not by default. To configure your cache store, provide the reference:
+
+```ruby
+Darrrr.cache = Dalli::Client.new('localhost:11211', options)
+```
+
+The spec disallows `http` URIs for basic security, but sometimes we don't have this setup locally.
+
+```ruby
+Darrrr.allow_unsafe_urls = true
+```
+
+## Provider registration
+
+In order to allow a site to act as a provider, it must be "registered" on boot to prevent unauthorized providers from managing tokens.
+
+```ruby
+# Only configure this if you are acting as a recovery provider
+Darrrr.register_account_provider("https://github.com")
+
+# Only configure this if you are acting as an account provider
+Darrrr.register_recovery_provider("https://www.facebook.com")
+```
+
+## Custom crypto
+
+Create a module that responds to `Module.sign`, `Module.verify`, `Module.decrypt`, and `Module.encrypt`. You can use the template below. I recommend leaving the `#verify` method as is unless you have a compelling reason to override it.
+
+### Global config
+
+Set `Darrrr.custom_encryptor = MyCustomEncryptor`
+
+### On-demand
+
+```ruby
+Darrrr.with_encryptor(MyCustomEncryptor) do
+  # perform DAR actions using MyCustomEncryptor as the crypto provider
+  token = Darrrr.this_account_provider.generate_recovery_token(data: "foo", audience: recovery_provider)
+end
+```
+
+```ruby
+module MyCustomEncryptor
+  class << self
+    # Encrypts the data in an opaque way
+    #
+    # data: the secret to be encrypted
+    #
+    # returns a byte array representation of the data
+    def encrypt(data)
+
+    end
+
+    # Decrypts the data
+    #
+    # ciphertext: the byte array to be decrypted
+    #
+    # returns a string
+    def decrypt(ciphertext)
+
+    end
+
+    # payload: binary serialized recovery token (to_binary_s).
+    #
+    # key: the private EC key used to sign the token
+    #
+    # returns signature in ASN.1 DER r + s sequence
+    def sign(payload, key)
+
+    end
+
+    # payload: token in binary form
+    # signature: signature of the binary token
+    # key: the EC public key used to verify the signature
+    #
+    # returns true if signature validates the payload
+    def verify(payload, signature, key)
+      # typically, the default verify function should be used to ensure compatibility
+      Darrrr::DefaultEncryptor.verify(payload, signature, key)
+    end
+  end
+end
+```
+
+## Example implementation
+
+I strongly suggest you read the specification, specifically section 3.1 (save-token) and 3.5 (recover account) as they contain the most dangerous operations.
+
+**NOTE:** this is NOT meant to be a complete implementation, it is just the starting point. Crucial aspects such as authentication, audit logging, out of band notifications, and account provider persistence are not implemented.
+
+* [Account Provider](controllers/account_provider_controller.rb) (save-token-return, recover-account-return)
+* [Recovery Provider](controllers/recovery_provider_controller.rb) (save-token, recover-account)
+* [Configuration endpoint](controllers/well_known_config_controller.rb) (`/.well-known/delegated-account-recovery/configuration`)
+
+Specifically, the gem exposes the following APIs for manipulating tokens.
+* Account Provider
+  * [Generating](https://github.com/github/darrrr/blob/faafda5b1773e077c9c10b55b46216f97d13cd3b/lib/github/delegated_account_recovery/account_provider.rb#L49) a token
+  * Signing ([`#seal`](https://github.com/github/darrrr/blob/faafda5b1773e077c9c10b55b46216f97d13cd3b/lib/github/delegated_account_recovery/crypto_helper.rb#L13)) a token
+  * Verifying ([`#unseal`](https://github.com/github/darrrr/blob/faafda5b1773e077c9c10b55b46216f97d13cd3b/lib/github/delegated_account_recovery/crypto_helper.rb#L30)) a countersigned token
+* Recovery Provider
+  * Verifying ([`#unseal`](https://github.com/github/darrrr/blob/faafda5b1773e077c9c10b55b46216f97d13cd3b/lib/github/delegated_account_recovery/crypto_helper.rb#L30)) a token
+  * [Countersigning](https://github.com/github/darrrr/blob/faafda5b1773e077c9c10b55b46216f97d13cd3b/lib/github/delegated_account_recovery/recovery_provider.rb#L60) a token
+
+### Development
+
+Local development assumes a Mac OS environment with [homebrew](https://brew.sh/) available. Postgres and phantom JS will be installed.
+
+Run `./script/bootstrap` then run `./script/server`
+
+* Visit `http://localhost:9292/account-provider`
+  * (Optionally) Record the random number for verification
+  * Click "connect to http://localhost:9292"
+* You'll see some debug information on the page.
+  * Click "setup recovery".
+* If recovery setup was successful, click "Recovery Setup Successful"
+* Click the "recover now?" link
+* You'll see an intermediate page, where more debug information is presented. Click "recover token"
+* You should be sent back to your host
+  * And see something like `Recovered data: <the secret from step 1>`
+
+### Tests
+
+Run `./script/test` to run all tests.
+
+## Deploying to heroku
+
+Use `heroku config:set` to set the environment variables listed in [script/setup](/script/setup). Additionally, run:
+
+```
+heroku config:set HOST_URL=$(heroku info -s | grep web_url | cut -d= -f2)
+```
+
+Push your app to heroku:
+
+```
+git push heroku <branch-name>:master
+```
+
+Migrate the database:
+
+```
+heroku run rake db:migrate
+```
+
+Use the app!
+
+```
+heroku restart
+heroku open
+```
+
+## Roadmap
+
+* Add support for `token-status` endpoints as defined by the spec
+* Add async API as defined by the spec
+* Implement token binding as part of the async API
+
+## Don't want to run `./script` entries?
+
+See `script/setup` for the environment variables that need to be set.
+
+## Contributions
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+`darrrr` is licensed under the [MIT license](LICENSE.md).

data/Rakefile

@@ -0,0 +1,42 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'net/http'
+require 'net/https'
+require 'date'
+
+require_relative "app"
+require_relative "lib/darrrr"
+require "sinatra/activerecord/rake"
+
+namespace :db do
+  task :load_config do
+    require "./app"
+  end
+end
+
+
+unless ENV["RACK_ENV"] == "production"
+  require 'rspec/core/rake_task'
+  desc "Run RSpec"
+  RSpec::Core::RakeTask.new do |t|
+    t.verbose = false
+    t.rspec_opts = "--format progress"
+  end
+
+  task default: :spec
+end
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SecureHeaders'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/darrrr.rb

@@ -0,0 +1,9 @@
+require "bindata"
+require "openssl"
+require "addressable"
+require "forwardable"
+require "faraday"
+
+require_relative "github/delegated_account_recovery"
+
+Darrrr = GitHub::DelegatedAccountRecovery

data/lib/github/delegated_account_recovery.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "bindata"
+require "openssl"
+
+require_relative "delegated_account_recovery/constants"
+require_relative "delegated_account_recovery/crypto_helper"
+require_relative "delegated_account_recovery/recovery_token"
+require_relative "delegated_account_recovery/provider"
+require_relative "delegated_account_recovery/account_provider"
+require_relative "delegated_account_recovery/recovery_provider"
+require_relative "delegated_account_recovery/serialization/recovery_token_writer"
+require_relative "delegated_account_recovery/serialization/recovery_token_reader"
+require_relative "delegated_account_recovery/cryptors/default/default_encryptor"
+require_relative "delegated_account_recovery/cryptors/default/encrypted_data"
+require_relative "delegated_account_recovery/cryptors/default/encrypted_data_io"
+
+module GitHub
+  module DelegatedAccountRecovery
+    # Represents a binary serialization error
+    class RecoveryTokenSerializationError < StandardError; end
+
+    # Represents invalid data within a valid token
+    #  (e.g. wrong `version` number, invalid token `type`)
+    class TokenFormatError < StandardError; end
+
+    # Represents all crypto errors
+    #   (e.g. invalid keys, invalid signature, decrypt failures)
+    class CryptoError < StandardError; end
+
+    # Represents providers supplying invalid configurations
+    #  (e.g. non-https URLs, missing required fields, http errors)
+    class ProviderConfigError < StandardError; end
+
+    # Represents an invalid countersigned recovery token.
+    #  (e.g. invalid signature, invalid nested token, unregistered provider, stale tokens)
+    class CountersignedTokenError < StandardError
+      attr_reader :key
+      def initialize(message, key)
+        super(message)
+        @key = key
+      end
+    end
+
+    # Represents an invalid recovery token.
+    #  (e.g. invalid signature, unregistered provider, stale tokens)
+    class RecoveryTokenError < StandardError; end
+
+    # Represents a call to to `recovery_provider` or `account_provider` that
+    # has not been registered.
+    class UnknownProviderError < ArgumentError; end
+
+    include Constants
+
+    class << self
+      REQUIRED_CRYPTO_OPS = [:sign, :verify, :encrypt, :decrypt].freeze
+      # recovery provider data is only loaded (and cached) upon use.
+      attr_accessor :recovery_providers, :account_providers, :cache, :allow_unsafe_urls,
+        :privacy_policy, :icon_152px, :authority
+
+      # Find and load remote recovery provider configuration data.
+      #
+      # provider_origin: the origin that contains the config data in a well-known
+      # location.
+      def recovery_provider(provider_origin)
+        unless self.recovery_providers
+          raise "No recovery providers configured"
+        end
+        if self.recovery_providers.include?(provider_origin)
+          RecoveryProvider.new(provider_origin).load
+        else
+          raise UnknownProviderError, "Unknown recovery provider: #{provider_origin}"
+        end
+      end
+
+      # Permit an origin to act as a recovery provider.
+      #
+      # provider_origin: the origin to permit
+      def register_recovery_provider(provider_origin)
+        self.recovery_providers ||= []
+        self.recovery_providers << provider_origin
+      end
+
+      # Find and load remote account provider configuration data.
+      #
+      # provider_origin: the origin that contains the config data in a well-known
+      # location.
+      def account_provider(provider_origin)
+        unless self.account_providers
+          raise "No account providers configured"
+        end
+        if self.account_providers.include?(provider_origin)
+          AccountProvider.new(provider_origin).load
+        else
+          raise UnknownProviderError, "Unknown account provider: #{provider_origin}"
+        end
+      end
+
+      # Permit an origin to act as an account provider.
+      #
+      # account_origin: the origin to permit
+      def register_account_provider(account_origin)
+        self.account_providers ||= []
+        self.account_providers << account_origin
+      end
+
+      # Provide a reference to the account provider configuration for this web app
+      def this_account_provider
+        AccountProvider.this
+      end
+
+      # Provide a reference to the recovery provider configuration for this web app
+      def this_recovery_provider
+        RecoveryProvider.this
+      end
+
+      # Returns a hash of all configuration values, recovery and account provider.
+      def account_and_recovery_provider_config
+        provider_data = Darrrr.this_account_provider.try(:to_h) || {}
+
+        if Darrrr.this_recovery_provider
+          provider_data.merge!(recovery_provider_config) do |key, lhs, rhs|
+            unless lhs == rhs
+              raise ArgumentError, "inconsistent config value detected #{key}: #{lhs} != #{rhs}"
+            end
+
+            lhs
+          end
+        end
+
+        provider_data
+      end
+
+      # returns the account provider information in hash form
+      def account_provider_config
+        this_account_provider.to_h
+      end
+
+      # returns the account provider information in hash form
+      def recovery_provider_config
+        this_recovery_provider.to_h
+      end
+
+      def with_encryptor(encryptor)
+        raise ArgumentError, "A block must be supplied" unless block_given?
+        unless valid_encryptor?(encryptor)
+          raise ArgumentError, "custom encryption class must respond to all of #{REQUIRED_CRYPTO_OPS}"
+        end
+
+        Thread.current[:darrrr_encryptor] = encryptor
+        yield
+      ensure
+        Thread.current[:darrrr_encryptor] = nil
+      end
+
+      # Returns the crypto API to be used. A thread local instance overrides the
+      # globally configured value which overrides the default encryptor.
+      def encryptor
+        Thread.current[:darrrr_encryptor] || @encryptor || DefaultEncryptor
+      end
+
+      # Overrides the global `encryptor` API to use
+      #
+      # encryptor: a class/module that responds to all +REQUIRED_CRYPTO_OPS+.
+      def custom_encryptor=(encryptor)
+        if valid_encryptor?(encryptor)
+          @encryptor = encryptor
+        else
+          raise ArgumentError, "custom encryption class must respond to all of #{REQUIRED_CRYPTO_OPS}"
+        end
+      end
+
+      private def valid_encryptor?(encryptor)
+        REQUIRED_CRYPTO_OPS.all? {|m| encryptor.respond_to?(m)}
+      end
+    end
+  end
+end