zero_auth 0.0.1.beta → 0.0.2.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3011392374e4a055d4748a3433882c41e2c4558a
-  data.tar.gz: 3cdbc75b4eaff08e286acc940f0019f8cd961921
+  metadata.gz: 8e5293b8a8a5c64cb80f819e0afc5fe0da191223
+  data.tar.gz: 52511c99d61691eaf31db9a9effb837ef285ed0d
 SHA512:
-  metadata.gz: 7884a750cfb742837bdf495fdd64790dcd82ee550a3a29f876f74eee3b87f824f9717ba0de47f02ce50057281ccd62538c8d464fd6b7e0c7253842899ac2967b
-  data.tar.gz: f142dbaf426d7790f7bad103c4ee599b93c790edbd21bdac24ec53a65f30d79efd7d39070bee2a452958a8194b79419e4547d26131c5ef2e21278b7337746f96
+  metadata.gz: 32125971bae43ce2cae06f9dab77afae3eb58daa9f834ad288024067facd7afff2d5c1a9793e2c8e881419c6e30809ea7076203fc7dc4937cff7b40e7cac8c3a
+  data.tar.gz: 84c2a65e27f0a4d64f642196fdff381fb76105141633b3400fe6882879c766ae13b92c2255d87919e0e531968264bc29a54e3673275a3feddf235d24cf9072c3

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+
+install: "bundle install"
+
+script: "bundle exec rake"
+
+rvm:
+  - 2.0.0
+  - 2.1.0

data/.yardopts

@@ -0,0 +1,2 @@
+--markup=markdown
+lib/**/*.rb

data/README.md

@@ -1,7 +1,9 @@
-# ZeroAuth
+# ZeroAuth [![Build Status](https://travis-ci.org/bschaeffer/zero_auth.svg?branch=master)](https://travis-ci.org/bschaeffer/zero_auth) [![Inline docs](http://inch-ci.org/github/bschaeffer/zero_auth.png?branch=master)](http://inch-ci.org/github/bschaeffer/zero_auth)
 
 **Zero configuration** authentication starter for your Rails project.
 
+* Docs: http://rdoc.info/github/bschaeffer/zero_auth
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,8 +20,60 @@ Or install it yourself as:
 
 ## Usage
 
-Coming Soon...
+### Models
+
+#### `ZeroAuth::Model::Password`
+
+* Docs: http://rdoc.info/github/bschaeffer/zero_auth/ZeroAuth/Model/Password
+* Provides password salting and hashing using `BCrypt`.
+* Instance method authentication.
+* **Requires** `password_salt` and `password_hash` attributes.
+
+```ruby
+class User
+  include ZeroAuth::Model::Password
+  attr_accessor :password_salt, :password_hash
+end
+
+user = User.new
+user.password = 'password'
+
+user.password_salt # => BCrypt::Engine.generate_salt
+user.password_hash # => BCrypt::Password
+
+user.has_password?('password') # => true
+user.has_password?('pa$$w0rD') # => false
+
+user.authenticate!('password') # => true
+user.authenticate!('pa$$word') # => raises ZeroAuth::Unauthorized
+```
+
+##### Rails Setup
+
+```ruby
+# migration
+change_table :users do |t|
+  t.string :password_salt, null: false, default: ""
+  t.string :password_hash, null: false, default: ""
+end
+
+# model
+class User < ActiveRecord::Base
+  include ZeroAuth::Model::Password
+end
+```
+
+##### MongoMapper Setup
+
+```ruby
+class User < ActiveRecord::Base
+  include MongoMapper::Document
+  include ZeroAuth::Model::Password
 
+  key :password_salt, String
+  key :password_hash, String
+end
+```
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,5 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/zero_auth/model/password.rb

@@ -0,0 +1,183 @@
+module ZeroAuth
+  module Model
+    # The `Password` module includes the following features:
+    #
+    # * Password **salting** and **hashing** using `BCrypt`.
+    # * Instance level authentication method.
+    #
+    # ...yup, that's it. The idea is to provide a quick, secure way to store
+    # encrypted passwords. It is almost identical to Rails' own
+    # [has_secure_password](http://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html)
+    # method, with the only exception being ZeroAuth uses a unique salt stored
+    # alongside and used to compute a password's hash.
+    #
+    # ### Requirement
+    #
+    # Your object must be able to write to the `password_salt` and the
+    # `password_hash` attributes (we handle the `password` attribute), so you
+    # might want to do something like this in a Rails migration:
+    #
+    # ```ruby
+    # change_table :users do |t|
+    #   t.string :password_salt, null: false, default: ""
+    #   t.string :password_hash, null: false, default: ""
+    # end
+    # ```
+    #
+    # ...or something like this using [`MongoMapper`](http://mongomapper.com/):
+    #
+    # ```ruby
+    # class User
+    #   include MongoMapper::Document
+    #   include ZeroAuth::Model::Password
+    #
+    #   key :password_salt, String
+    #   key :password_hash, String
+    # end
+    # ```
+    #
+    # ### Usage
+    #
+    # ```ruby
+    # class User < ActiveRecord::Base
+    #   include ZeroAuth::Model::Password
+    # end
+    #
+    # user = User.create(email: 'email@me.com', password: 'password')
+    #
+    # user.has_password?('password') # => true
+    # user.has_password?('pa$$w0rD') # => false
+    #
+    # user.authenticate!('password') # => true
+    # user.authenticate!('pa$$word') # => raises ZeroAuth::Unauthorized
+    # ```
+    #
+    # ### Implementing Validations
+    #
+    # This module provides a {#requires_password?} helper method that, by
+    # default, simply checks whether this object is a `#new_record?` (if
+    # we can check that) or if the `#password` attributes is `empty?`.
+    #
+    # Again, with ActiveRecord or ActiveModel as an example, you can utilize it
+    # like this:
+    #
+    # ```ruby
+    # class User < ActiveRecord
+    #   include ZeroAuth::Model::Password
+    #
+    #   with_options if: :requires_password? do |pw|
+    #     pw.validates :password, length: {in: 8..40}, confirmation: true
+    #   end
+    # end
+    # ```
+    #
+    # You can also simply override the {#requires_password?} method to require
+    # validation when an `:old_password` attribute is present:
+    #
+    # ```ruby
+    # attr_accesor :old_password
+    #
+    # def requires_password?
+    #   super || old_password.present?
+    # end
+    # ```
+    #
+    # ### Customize Authentication Class Method
+    #
+    # The {ZeroAuth::Model::Password} module leaves record retreival and the
+    # exact authentication tree up to the developer, but implementing a
+    # custom class method is trivial. An example using `ActiveRecord` might look
+    # something like this:
+    #
+    # ```ruby
+    # class User < ActiveRecord::Base
+    #   include ZeroAuth::Model::Password
+    #
+    #   def self.authenticate(email, password)
+    #     begin
+    #       self.authenticate!(email, password)
+    #     rescue ZeroAuth::Unauthorized
+    #     end
+    #   end
+    #
+    #   def self.authenticate!(email, password)
+    #     begin
+    #       record = self.find_by!(email: email)
+    #       record.authenticate!(password) && record
+    #     rescue ActiveRecord::RecordNotFound
+    #       fail ZeroAuth::Unauthorized
+    #     end
+    #   end
+    # end
+    # ```
+    #
+    # **Note** the use of the {ZeroAuth::Unauthorized} exception. This is a
+    # custom error class provided to allow a standard way for your application
+    # to capture exceptions regarding authentication and authorization.
+    #
+    # The implementation above is certainly a personal perference, but the
+    # logic, again, is left up to you.
+    #
+    module Password
+
+      # Calls `attr_reader :password` on the including class.
+      #
+      def self.included(base)
+        base.class_eval { attr_reader :password }
+      end
+
+      # If the given password is not `nil?`, generates a `password_salt` and
+      # encrypts the given password into the `password_hash` using that salt.
+      # The salt and hash are generated using {ZeroAuth::Password.generate_salt}
+      # and {ZeroAuth::Utils.create_password}.
+      #
+      # @param unencrypted_password [String] the unencrypted password_attribute
+      # @return [Mixed] the unencrypted password
+      #
+      def password=(unencrypted_password)
+        if unencrypted_password.nil?
+          @password = nil
+          self.password_salt = nil
+          self.password_hash = nil
+        else
+          @password = unencrypted_password
+          self.password_salt = ZeroAuth::Password.generate_salt
+          self.password_hash = ZeroAuth::Password.create(password, password_salt)
+        end
+      end
+
+      # Checks that the object is a `#new_record?` (if we can) or that the
+      # `password` attribute is not empty.
+      #
+      # @return [Boolean]
+      #
+      def requires_password?
+        is_new = (respond_to?(:new_record?) && new_record?)
+        is_new || !ZeroAuth::Utils.empty?(password)
+      end
+
+      # A helper method that takes a given password and raises a
+      # {ZeroAuth::Unauthorized} error if the call to `has_password?` fails.
+      #
+      # @params password [String] password to test
+      #
+      # @return [Nil]
+      # @raise {ZeroAuth::Unauthorized} if the given password is not valid
+      #
+      def authenticate!(test_password)
+        has_password?(test_password) || fail(ZeroAuth::Unauthorized)
+      end
+
+      # Compares the given password with the current password attributes using
+      # {ZeroAuth::Utils.compare_password}.
+      #
+      # @param test_password [String] password to test
+      # @return [Boolean]
+      #
+      def has_password?(test_password)
+        return false unless !ZeroAuth::Utils.empty?(password_hash)
+        ZeroAuth::Password.compare(password_hash, password_salt, test_password)
+      end
+    end
+  end
+end

data/lib/zero_auth/password.rb

@@ -0,0 +1,39 @@
+require 'bcrypt'
+
+module ZeroAuth
+  class Password
+
+    # @return [String] a salt created by `BCrypt::Engine.generate_salt`
+    #
+    def self.generate_salt
+      BCrypt::Engine.generate_salt
+    end
+
+    # Generates a `BCrypt::Password` with a hard-coded cost of **9** (which
+    # will probably change soon).
+    #
+    # @param password [String] the given password
+    # @param salt [Sting] the password salt
+    #
+    # @return [BCrypt::Password]
+    #
+    def self.create(password, salt)
+      BCrypt::Password.create("#{password}#{salt}", cost: 9)
+    end
+
+    # Compares a given encrypted password and the salt used to generate it with
+    # an unencrypted_password. Uses {ZeroAuth::Utils.secure_compare}.
+    #
+    # @param encrypted [String] the encrypted password
+    # @param salt [String] the salt used to generate that password
+    # @param unencrypted [String] the plain text password to compare
+    #
+    # @return [Boolean] true if they are equal, false if they aren't
+    #
+    def self.compare(encrypted, salt, unencrypted)
+      bcrypt = BCrypt::Password.new(encrypted)
+      password = BCrypt::Engine.hash_secret("#{unencrypted}#{salt}", bcrypt.salt)
+      ZeroAuth::Utils.secure_compare(password, encrypted)
+    end
+  end
+end

data/lib/zero_auth/utils.rb

@@ -0,0 +1,31 @@
+require 'bcrypt'
+
+module ZeroAuth
+  class Utils
+
+    # Uses a "constant time" comparison algorithm I would never have thought
+    # about so I copied it line for line from `Devise.secure_compare`:
+    #
+    # https://github.com/plataformatec/devise/blob/11c88754791322c8c4c5c123149f5435eda3b932/lib/devise.rb#L481
+    #
+    # @params a [String] first string to compare
+    # @params second [String] second string to compare
+    #
+    # @return [Boolean] true if they are equal, false if they aren't
+    #
+    def self.secure_compare(a, b)
+      return false if empty?(a) || empty?(b) || a.bytesize != b.bytesize
+      l = a.unpack "C#{a.bytesize}"
+
+      res = 0
+      b.each_byte { |byte| res |= byte ^ l.shift }
+      res == 0
+    end
+
+    #
+    # @!visibility private
+    def self.empty?(v)
+      v.respond_to?(:empty?) ? v.empty? : !v
+    end
+  end
+end

data/lib/zero_auth/version.rb

@@ -1,3 +1,3 @@
 module ZeroAuth
-  VERSION = "0.0.1.beta"
+  VERSION = "0.0.2.beta"
 end

data/lib/zero_auth.rb

@@ -1,4 +1,16 @@
 require "zero_auth/version"
 
 module ZeroAuth
+  autoload :Utils, 'zero_auth/utils'
+  autoload :Password, 'zero_auth/password'
+
+  module Model
+    autoload :Password, 'zero_auth/model/password'
+  end
+
+  # Exception raised througout the library when a method expected to
+  # perform some type of authentication on user supplied parameters cannot be
+  # authenticated.
+  #
+  class Unauthorized < StandardError; end
 end

data/spec/lib/zero_auth/model/password_spec.rb

@@ -0,0 +1,86 @@
+require 'spec_helper'
+
+RSpec.describe ZeroAuth::Model::Password do
+  class User
+    include ZeroAuth::Model::Password
+    attr_accessor :password_salt, :password_hash
+  end
+
+  class ArUser < User
+    def new_record?
+      false
+    end
+  end
+
+  let(:user) { User.new }
+  before { user.password = "password" }
+
+  describe "#password=" do
+    it "sets the hash and salt to nil given a nil password" do
+      user.password = nil
+      expect(user.password_salt).to eq(nil)
+      expect(user.password_hash).to eq(nil)
+    end
+
+    it "sets the hash and salt given a non-nil password" do
+      user.password = "password"
+      salt = user.password_salt
+      hash = user.password_hash
+
+      expect(salt).to_not be_empty
+      expect(hash).to_not be_empty
+
+      expected_salt = ZeroAuth::Password.generate_salt
+      expect(salt.length).to eq(expected_salt.length)
+
+      hash_result = ZeroAuth::Password.compare(hash, salt, "password")
+      expect(hash_result).to eq(true)
+    end
+  end
+
+  describe "#has_password?" do
+    it "returns true given a valid password" do
+      expect(user.has_password?("password")).to eq(true)
+    end
+
+    it "returns false for an invalid password" do
+      expect(user.has_password?("test")).to eq(false)
+    end
+  end
+
+  describe "#authenticate!" do
+    it "raises a ZeroAuth::Unauthorized error for an invalid password" do
+      user.password = "password"
+      expect{user.authenticate!("other")}.to raise_error(ZeroAuth::Unauthorized)
+    end
+
+    it "returns true for a valid password" do
+      user.password = "password"
+      expect(user.authenticate!("password")).to eq(true)
+    end
+  end
+
+  describe "#requires_password?" do
+    let(:password) { nil }
+    before { user.password = password }
+    subject { user.requires_password? }
+
+    context "when the object is not a new #new_record?" do
+      context "and its password_hash is empty" do
+        it { is_expected.to eq(false) }
+      end
+
+      context "and its password is not-empty" do
+        let(:password) { "password" }
+        it { is_expected.to eq(true) }
+      end
+    end
+
+    context "when the object is a #new_record?" do
+      let(:user) { ArUser.new }
+      before { allow(user).to receive(:new_record?) { true } }
+
+      it { is_expected.to eq(true) }
+    end
+  end
+end

data/spec/lib/zero_auth/password_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+RSpec.describe ZeroAuth::Password do
+
+  describe ".generate_salt" do
+    it "returns a BCrypt generated salt" do
+      expect(ZeroAuth::Password.generate_salt).to match(/^\$2a\$\d+\$/)
+    end
+  end
+
+  describe ".create" do
+    it "returns a BCrypt::Password" do
+      password = ZeroAuth::Password.create("password", "salt")
+      expect(password).to be_a(BCrypt::Password)
+    end
+  end
+
+  describe ".compare" do
+    let(:password) { ZeroAuth::Password.create("password", "salt").to_s }
+
+    it "returns true for matching passwords" do
+      result = ZeroAuth::Password.compare(password, "salt", "password")
+      expect(result).to eq(true)
+    end
+
+    it "returns false for non-matching passwords" do
+      result = ZeroAuth::Password.compare(password, "salt", "other")
+      expect(result).to eq(false)
+    end
+  end
+end

data/spec/lib/zero_auth/utils_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+RSpec.describe ZeroAuth::Utils do
+
+  describe ".secure_compare" do
+    it "returns true for equal values" do
+      expect(ZeroAuth::Utils.secure_compare("password", "password")).to eq(true)
+    end
+
+    it "returns false for non-equal values" do
+      expect(ZeroAuth::Utils.secure_compare("password", "other")).to eq(false)
+    end
+
+    it "returns false for empty strings" do
+      expect(ZeroAuth::Utils.secure_compare("password", "")).to eq(false)
+      expect(ZeroAuth::Utils.secure_compare("", "password")).to eq(false)
+      expect(ZeroAuth::Utils.secure_compare("", "")).to eq(false)
+    end
+
+    it "returns false for nil values" do
+      expect(ZeroAuth::Utils.secure_compare("password", nil)).to eq(false)
+      expect(ZeroAuth::Utils.secure_compare(nil, "password")).to eq(false)
+      expect(ZeroAuth::Utils.secure_compare(nil, nil)).to eq(false)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require 'bundler/setup'
+Bundler.setup
+
+require 'zero_auth'
+
+RSpec.configure do |config|
+  if config.files_to_run.one?
+    config.default_formatter = 'doc'
+  end
+
+  config.order = :random
+  Kernel.srand config.seed
+
+  config.expect_with :rspec do |expectations|
+    expectations.syntax = :expect
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.syntax = :expect
+    mocks.verify_partial_doubles = true
+  end
+end

data/zero_auth.gemspec

@@ -17,6 +17,11 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^spec/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake"
+  spec.add_dependency 'bcrypt', '~> 3.1.7'
+
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'redcarpet'
+  spec.add_development_dependency 'yard'
 end

metadata

@@ -1,41 +1,97 @@
 --- !ruby/object:Gem::Specification
 name: zero_auth
 version: !ruby/object:Gem::Version
-  version: 0.0.1.beta
+  version: 0.0.2.beta
 platform: ruby
 authors:
 - Braden Schaeffer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-13 00:00:00.000000000 Z
+date: 2014-08-27 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bcrypt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.7
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Zero configuration authentication starter for Rails.
@@ -45,13 +101,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/zero_auth.rb
+- lib/zero_auth/model/password.rb
+- lib/zero_auth/password.rb
+- lib/zero_auth/utils.rb
 - lib/zero_auth/version.rb
+- spec/lib/zero_auth/model/password_spec.rb
+- spec/lib/zero_auth/password_spec.rb
+- spec/lib/zero_auth/utils_spec.rb
+- spec/spec_helper.rb
 - zero_auth.gemspec
 homepage: https://github.com/bschaeffer/zero_auth
 licenses:
@@ -63,18 +129,23 @@ 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: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Zero configuration authentication starter for Rails.
-test_files: []
+test_files:
+- spec/lib/zero_auth/model/password_spec.rb
+- spec/lib/zero_auth/password_spec.rb
+- spec/lib/zero_auth/utils_spec.rb
+- spec/spec_helper.rb
+has_rdoc: