pwned 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a4cfc835ea737e4c8f06f0abc5681f36321d94cb0224a1628ba3bbc46276d68
-  data.tar.gz: 2c48c27b0e9308431fe7c47d00d74318e55f2bff60456d8222fc108b7915318c
+  metadata.gz: 4661790082f543ba897baf211da660c7a4f654444121f4ff3ba08542c08c412b
+  data.tar.gz: f52a3f3cf36d461e8704a632f97829a5d9f871d9916a55687d4a0b2156b44b75
 SHA512:
-  metadata.gz: 5aaa679b1268b7e2eaa17bebab180a071c286080965602cd50d0e2c1f5b6b92b58c970fbf12e5678c10d4570907632b4346a345ea904820370505f205b7d51d6
-  data.tar.gz: cf95e423abffe290bf3de0bfe6c1dff7da73eb8c6c0b574ca97ab63ad82d27a417caa35136cccf3dd4407437b8e00f77421144ad50487b5d8a8502438fa660cb
+  metadata.gz: c114c3ca6e7667d1760ad2ae5dabcc7bf8d14b91e42788f7e36bba716eecd9bef6e1847e93dd12df4f8afed19460d26a068dc22ffb2270ceef8dc342f81690e0
+  data.tar.gz: c19d20d765cd57e64468c27a3e8f134e53d8f6e9ae22497c2d94a315a584e2e19b1913d47b37e89c9525ce80d85d10d43437a623d211766aa7242dbe1144e906

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Ongoing [☰](https://github.com/philnash/pwned/compare/v2.0.2...master)
 
+## 2.1.0 (July 8, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.2...v2.1.0)
+
+- Minor updates
+
+  - Adds `Pwned::HashedPassword` class which is initializd with a SHA1 hash to
+    query the API with so that the lookup can be done in the background without
+    storing passwords. Fixes #19, thanks [@paprikati](https://github.com/paprikati).
+
 ## 2.0.2 (May 20, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.1...v2.0.2)
 
 - Minor fix
@@ -10,7 +18,7 @@
     result in a `nil` which caused trouble with string concatenation. This
     avoids that scenario. Fixes #18, thanks [@flori](https://github.com/flori).
 
-## 2.0.1 (January 14, 2019) [☰](https://github.com/philnash/pwned/compare/v2.0.0...v2.0.1)
+## 2.0.1 (January 14, 2020) [☰](https://github.com/philnash/pwned/compare/v2.0.0...v2.0.1)
 
 - Minor updates
 

data/README.md

@@ -4,22 +4,30 @@ An easy, Ruby way to use the Pwned Passwords API.
 
 [![Gem Version](https://badge.fury.io/rb/pwned.svg)](https://rubygems.org/gems/pwned) [![Build Status](https://travis-ci.org/philnash/pwned.svg?branch=master)](https://travis-ci.org/philnash/pwned) [![Maintainability](https://codeclimate.com/github/philnash/pwned/badges/gpa.svg)](https://codeclimate.com/github/philnash/pwned/maintainability) [![Inline docs](https://inch-ci.org/github/philnash/pwned.svg?branch=master)](https://inch-ci.org/github/philnash/pwned)
 
-[API docs](https://philnash.github.io/pwned/) | [GitHub repo](https://github.com/philnash/pwned)
+[API docs](https://www.rubydoc.info/gems/pwned) | [GitHub repo](https://github.com/philnash/pwned)
 
 ## Table of Contents
 
-* [About](#about)
-* [Installation](#installation)
-* [Usage](#usage)
-  * [Plain Ruby](#plain-ruby)
-  * [Rails (ActiveRecord)](#activerecord-validator)
-  * [Devise](#devise)
-  * [Command line](#command-line)
-* [How Pwned is Pi?](#how-pwned-is-pi)
-* [Development](#development)
-* [Contributing](#contributing)
-* [License](#license)
-* [Code of Conduct](#code-of-conduct)
+- [Pwned](#pwned)
+  - [Table of Contents](#table-of-contents)
+  - [About](#about)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Plain Ruby](#plain-ruby)
+      - [Advanced](#advanced)
+    - [ActiveRecord Validator](#activerecord-validator)
+      - [I18n](#i18n)
+      - [Threshold](#threshold)
+      - [Network Error Handling](#network-error-handling)
+      - [Custom Request Options](#custom-request-options)
+    - [Using Asynchronously](#using-asynchronously)
+    - [Devise](#devise)
+    - [Command line](#command-line)
+  - [How Pwned is Pi?](#how-pwned-is-pi)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Code of Conduct](#code-of-conduct)
 
 ## About
 
@@ -180,6 +188,17 @@ In addition to these options, HTTP headers can be specified with the `:headers`
   }
 ```
 
+### Using Asynchronously
+
+You may have a use case for hashing the password in advance, and then making the call to the Pwned api later
+(for example if you want to enqueue a job without storing the plaintext password):
+
+```ruby
+hashed_password = Pwned.hash_password(password)
+# some time later
+Pwned::HashPassword.new(hashed_password, request_options).pwned?
+```
+
 ### Devise
 
 If you are using Devise I recommend you use the [devise-pwned_password extension](https://github.com/michaelbanfield/devise-pwned_password) which is now powered by this gem.

data/bin/pwned

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 
-require 'pwned'
-require 'optparse'
-require 'io/console'
+require "pwned"
+require "optparse"
+require "io/console"
 
 options = {}
 parser = OptionParser.new do |opts|

data/lib/pwned.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "digest"
 require "pwned/version"
 require "pwned/error"
 require "pwned/password"
+require "pwned/hashed_password"
 
 begin
   # Load Rails and our custom validator
@@ -31,7 +33,7 @@ module Pwned
   # @param password [String] The password you want to check against the API.
   # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
   #   calling the API
-  # @option request_options [Symbol] :headers ({ "User-Agent" => '"Ruby Pwned::Password #{Pwned::VERSION}" })
+  # @option request_options [Symbol] :headers ({ "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}" })
   #   HTTP headers to include in the request
   # @return [Boolean] Whether the password appears in the data breaches or not.
   # @since 1.1.0
@@ -49,7 +51,7 @@ module Pwned
   # @param password [String] The password you want to check against the API.
   # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
   #   calling the API
-  # @option request_options [Symbol] :headers ({ "User-Agent" => '"Ruby Pwned::Password #{Pwned::VERSION}" })
+  # @option request_options [Symbol] :headers ({ "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}" })
   #   HTTP headers to include in the request
   # @return [Integer] The number of times the password has appeared in the data
   #   breaches.
@@ -57,4 +59,18 @@ module Pwned
   def self.pwned_count(password, request_options={})
     Pwned::Password.new(password, request_options).pwned_count
   end
+
+  ##
+  # Returns the full SHA1 hash of the given password in uppercase. This can be safely passed around your code
+  # before making the pwned request (e.g. dropped into a queue table).
+  #
+  # @example
+  #     Pwned.hash_password("password") #=> 5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8
+  #
+  # @param password [String] The password you want to check against the API
+  # @return [String] An uppercase SHA1 hash of the password
+  # @since 2.1.0
+  def self.hash_password(password)
+    Digest::SHA1.hexdigest(password).upcase
+  end
 end

data/lib/pwned/hashed_password.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "pwned/password_base"
+
+module Pwned
+  ##
+  # This class represents a hashed password. It does all the work of talking to the
+  # Pwned Passwords API to find out if the password has been pwned.
+  # @see https://haveibeenpwned.com/API/v2#PwnedPasswords
+  class HashedPassword
+    include PasswordBase
+    ##
+    # Creates a new hashed password object.
+    #
+    # @example A simple password with the default request options
+    #     password = Pwned::HashedPassword.new("ABC123")
+    # @example Setting the user agent and the read timeout of the request
+    #     password = Pwned::HashedPassword.new("ABC123", headers: { "User-Agent" => "My user agent" }, read_timout: 10)
+    #
+    # @param hashed_password [String] The hash of the password you want to check against the API.
+    # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
+    #   calling the API
+    # @option request_options [Symbol] :headers ({ "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}" })
+    #   HTTP headers to include in the request
+    # @raise [TypeError] if the password is not a string.
+    # @since 2.1.0
+    def initialize(hashed_password, request_options={})
+      raise TypeError, "hashed_password must be of type String" unless hashed_password.is_a? String
+      @hashed_password = hashed_password.upcase
+      @request_options = Hash(request_options).dup
+      @request_headers = Hash(request_options.delete(:headers))
+      @request_headers = DEFAULT_REQUEST_HEADERS.merge(@request_headers)
+    end
+  end
+end

data/lib/pwned/password.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "digest"
-require 'net/http'
+require "pwned/password_base"
 
 module Pwned
   ##
@@ -9,27 +8,7 @@ module Pwned
   # Pwned Passwords API to find out if the password has been pwned.
   # @see https://haveibeenpwned.com/API/v2#PwnedPasswords
   class Password
-    ##
-    # The base URL for the Pwned Passwords API
-    API_URL = "https://api.pwnedpasswords.com/range/"
-
-    ##
-    # The number of characters from the start of the hash of the password that
-    # are used to search for the range of passwords.
-    HASH_PREFIX_LENGTH = 5
-
-    ##
-    # The total length of a SHA1 hash
-    SHA1_LENGTH = 40
-
-    ##
-    # The default request headers that are used to make HTTP requests to the
-    # API. A user agent is provided as requested in the documentation.
-    # @see https://haveibeenpwned.com/API/v2#UserAgent
-    DEFAULT_REQUEST_HEADERS = {
-      "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}"
-    }.freeze
-
+    include PasswordBase
     ##
     # @return [String] the password that is being checked.
     # @since 1.0.0
@@ -46,7 +25,7 @@ module Pwned
     # @param password [String] The password you want to check against the API.
     # @param [Hash] request_options Options that can be passed to +Net::HTTP.start+ when
     #   calling the API
-    # @option request_options [Symbol] :headers ({ "User-Agent" => '"Ruby Pwned::Password #{Pwned::VERSION}" })
+    # @option request_options [Symbol] :headers ({ "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}" })
     #   HTTP headers to include in the request
     # @return [Boolean] Whether the password appears in the data breaches or not.
     # @raise [TypeError] if the password is not a string.
@@ -54,110 +33,10 @@ module Pwned
     def initialize(password, request_options={})
       raise TypeError, "password must be of type String" unless password.is_a? String
       @password = password
+      @hashed_password = Pwned.hash_password(password)
       @request_options = Hash(request_options).dup
       @request_headers = Hash(request_options.delete(:headers))
       @request_headers = DEFAULT_REQUEST_HEADERS.merge(@request_headers)
     end
-
-    ##
-    # Returns the full SHA1 hash of the given password in uppercase.
-    # @return [String] The full SHA1 hash of the given password.
-    # @since 1.0.0
-    def hashed_password
-      @hashed_password ||= Digest::SHA1.hexdigest(password).upcase
-    end
-
-    ##
-    # @example
-    #     password = Pwned::Password.new("password")
-    #     password.pwned? #=> true
-    #
-    # @return [Boolean] +true+ when the password has been pwned.
-    # @raise [Pwned::Error] if there are errors with the HTTP request.
-    # @raise [Pwned::TimeoutError] if the HTTP request times out.
-    # @since 1.0.0
-    def pwned?
-      pwned_count > 0
-    end
-
-    ##
-    # @example
-    #     password = Pwned::Password.new("password")
-    #     password.pwned_count #=> 3303003
-    #
-    # @return [Integer] the number of times the password has been pwned.
-    # @raise [Pwned::Error] if there are errors with the HTTP request.
-    # @raise [Pwned::TimeoutError] if the HTTP request times out.
-    # @since 1.0.0
-    def pwned_count
-      @pwned_count ||= fetch_pwned_count
-    end
-
-    private
-
-    attr_reader :request_options, :request_headers
-
-    def fetch_pwned_count
-      for_each_response_line do |line|
-        next unless line.start_with?(hashed_password_suffix)
-        # Count starts after the suffix, followed by a colon
-        return line[(SHA1_LENGTH-HASH_PREFIX_LENGTH+1)..-1].to_i
-      end
-
-      # The hash was not found, we can assume the password is not pwned [yet]
-      0
-    end
-
-    def for_each_response_line(&block)
-      begin
-        with_http_response "#{API_URL}#{hashed_password_prefix}" do |response|
-          response.value # raise if request was unsuccessful
-          stream_response_lines(response, &block)
-        end
-      rescue Timeout::Error => e
-        raise Pwned::TimeoutError, e.message
-      rescue => e
-        raise Pwned::Error, e.message
-      end
-    end
-
-    def hashed_password_prefix
-      hashed_password[0...HASH_PREFIX_LENGTH]
-    end
-
-    def hashed_password_suffix
-      hashed_password[HASH_PREFIX_LENGTH..-1]
-    end
-
-    # Make a HTTP GET request given the url and headers.
-    # Yields a `Net::HTTPResponse`.
-    def with_http_response(url, &block)
-      uri = URI(url)
-
-      request = Net::HTTP::Get.new(uri)
-      request.initialize_http_header(request_headers)
-      request_options[:use_ssl] = true
-
-      Net::HTTP.start(uri.host, uri.port, request_options) do |http|
-        http.request(request, &block)
-      end
-    end
-
-    # Stream a Net::HTTPResponse by line, handling lines that cross chunks.
-    def stream_response_lines(response, &block)
-      last_line = ''
-
-      response.read_body do |chunk|
-        chunk_lines = (last_line + chunk).lines
-        # This could end with half a line, so save it for next time. If
-        # chunk_lines is empty, pop returns nil, so this also ensures last_line
-        # is always a string.
-        last_line = chunk_lines.pop || ''
-        chunk_lines.each(&block)
-      end
-
-      yield last_line unless last_line.empty?
-    end
-
   end
 end

data/lib/pwned/password_base.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "digest"
+require "net/http"
+
+module Pwned
+  ##
+  # This class represents a password. It does all the work of talking to the
+  # Pwned Passwords API to find out if the password has been pwned.
+  # @see https://haveibeenpwned.com/API/v2#PwnedPasswords
+  module PasswordBase
+    ##
+    # The base URL for the Pwned Passwords API
+    API_URL = "https://api.pwnedpasswords.com/range/"
+
+    ##
+    # The number of characters from the start of the hash of the password that
+    # are used to search for the range of passwords.
+    HASH_PREFIX_LENGTH = 5
+
+    ##
+    # The total length of a SHA1 hash
+    SHA1_LENGTH = 40
+
+    ##
+    # The default request headers that are used to make HTTP requests to the
+    # API. A user agent is provided as requested in the documentation.
+    # @see https://haveibeenpwned.com/API/v2#UserAgent
+    DEFAULT_REQUEST_HEADERS = {
+      "User-Agent" => "Ruby Pwned::Password #{Pwned::VERSION}"
+    }.freeze
+
+    ##
+    # @example
+    #     password = Pwned::Password.new("password")
+    #     password.pwned? #=> true
+    #     password.pwned? #=> true
+    #
+    # @return [Boolean] +true+ when the password has been pwned.
+    # @raise [Pwned::Error] if there are errors with the HTTP request.
+    # @raise [Pwned::TimeoutError] if the HTTP request times out.
+    # @since 1.0.0
+    def pwned?
+      pwned_count > 0
+    end
+
+    ##
+    # @example
+    #     password = Pwned::Password.new("password")
+    #     password.pwned_count #=> 3303003
+    #
+    # @return [Integer] the number of times the password has been pwned.
+    # @raise [Pwned::Error] if there are errors with the HTTP request.
+    # @raise [Pwned::TimeoutError] if the HTTP request times out.
+    # @since 1.0.0
+    def pwned_count
+      @pwned_count ||= fetch_pwned_count
+    end
+
+    ##
+    # Returns the full SHA1 hash of the given password in uppercase.
+    # @return [String] The full SHA1 hash of the given password.
+    # @since 1.0.0
+    attr_reader :hashed_password
+
+    private
+
+    attr_reader :request_options, :request_headers
+
+    def fetch_pwned_count
+      for_each_response_line do |line|
+        next unless line.start_with?(hashed_password_suffix)
+        # Count starts after the suffix, followed by a colon
+        return line[(SHA1_LENGTH-HASH_PREFIX_LENGTH+1)..-1].to_i
+      end
+
+      # The hash was not found, we can assume the password is not pwned [yet]
+      0
+    end
+
+    def for_each_response_line(&block)
+      begin
+        with_http_response "#{API_URL}#{hashed_password_prefix}" do |response|
+          response.value # raise if request was unsuccessful
+          stream_response_lines(response, &block)
+        end
+      rescue Timeout::Error => e
+        raise Pwned::TimeoutError, e.message
+      rescue => e
+        raise Pwned::Error, e.message
+      end
+    end
+
+    def hashed_password_prefix
+      @hashed_password[0...HASH_PREFIX_LENGTH]
+    end
+
+    def hashed_password_suffix
+      @hashed_password[HASH_PREFIX_LENGTH..-1]
+    end
+
+    # Make a HTTP GET request given the url and headers.
+    # Yields a `Net::HTTPResponse`.
+    def with_http_response(url, &block)
+      uri = URI(url)
+
+      request = Net::HTTP::Get.new(uri)
+      request.initialize_http_header(request_headers)
+      request_options[:use_ssl] = true
+
+      Net::HTTP.start(uri.host, uri.port, request_options) do |http|
+        http.request(request, &block)
+      end
+    end
+
+    # Stream a Net::HTTPResponse by line, handling lines that cross chunks.
+    def stream_response_lines(response, &block)
+      last_line = ""
+
+      response.read_body do |chunk|
+        chunk_lines = (last_line + chunk).lines
+        # This could end with half a line, so save it for next time. If
+        # chunk_lines is empty, pop returns nil, so this also ensures last_line
+        # is always a string.
+        last_line = chunk_lines.pop || ""
+        chunk_lines.each(&block)
+      end
+
+      yield last_line unless last_line.empty?
+    end
+
+  end
+end