htauth 1.2.0 → 2.0.0

data/lib/htauth/console.rb

@@ -0,0 +1,31 @@
+require 'io/console'
+require 'htauth/error'
+
+# With many thanks to JEG2 - http://graysoftinc.com/terminal-tricks/random-access-terminal
+#
+module HTAuth
+  # Internal: Utility class for managing console input/output
+  class Console
+    attr_reader :input
+    attr_reader :output
+
+    def initialize(input = $stdin, output = $stdout)
+      @input = input
+      @output = output
+    end
+
+    def say(msg)
+      @output.puts msg
+    end
+
+    def ask(prompt)
+      output.print prompt
+      answer = input.noecho(&:gets)
+      output.puts
+      raise ConsoleError, "No input given" if answer.nil?
+      answer.strip!
+      raise ConsoleError, "No input given" if answer.length == 0
+      return answer
+    end
+  end
+end

data/lib/htauth/crypt.rb

@@ -1,8 +1,7 @@
 require 'htauth/algorithm'
 
 module HTAuth
-
-  # The basic crypt algorithm
+  # Internal: The basic crypt algorithm
   class Crypt < Algorithm
 
     def initialize(params = {})

data/lib/htauth/digest_entry.rb

@@ -1,18 +1,24 @@
-require 'htauth/errors'
+require 'htauth/error'
 require 'htauth/entry'
 require 'digest/md5'
 
 module HTAuth
-  class InvalidDigestEntry < StandardError ; end
-
-  # A single record in an htdigest file.  
+  # Internal: Object version of a single record from an htdigest file
   class DigestEntry
 
+    # Internal: The user of this entry
     attr_accessor :user
+    # Internal: The realm of this entry
     attr_accessor :realm
+    # Internal: The passwod digest of this entry
     attr_accessor :digest
 
     class << self
+      # Internal: Create an instance of this class from a line of text
+      #
+      # line - a line of text from a htdigest file
+      #
+      # Returns an instance of DigestEntry
       def from_line(line)
         parts = is_entry!(line)
         d = DigestEntry.new(parts[0], parts[1])
@@ -20,10 +26,16 @@ module HTAuth
         return d
       end
 
-      # test if a line is an entry, raise InvalidDigestEntry if it is not.
-      # an entry must be composed of 3 parts, username:realm:md5sum
-      # where username, and realm do not contain the ':' character 
-      # and the md5sum must be 32 characters long.
+      # Internal: test if the given line is valid for this Entry class
+      #
+      # A valid entry must be composed of 3 parts, username:realm:md5sum where
+      # username, and realm do not contain the ':' character; and md5sum must be
+      # 32 characters long
+      #
+      # line - a line of text from a file
+      #
+      # Returns the individual parts of the line
+      # Raises InvalidDigestEntry if it is not a a valid entry
       def is_entry!(line)
         raise InvalidDigestEntry, "line commented out" if line =~ /\A#/
         parts = line.strip.split(":")
@@ -33,7 +45,9 @@ module HTAuth
         return parts
       end
 
-      # test if a line is an entry and return true or false
+      # Internal: Returns whether or not the line is a valid entry
+      #
+      # Returns true or false
       def is_entry?(line)
         begin
           is_entry!(line)
@@ -44,29 +58,35 @@ module HTAuth
       end
     end
 
+    # Internal: Create a new Entry with the given user, realm and password
     def initialize(user, realm, password = "")
       @user     = user
       @realm    = realm
       @digest   = calc_digest(password)
     end
 
+    # Internal: Update the password of the entry with its new value
     def password=(new_password)
       @digest = calc_digest(new_password)
     end
 
+    # Internal: calculate the new digest of the given password
     def calc_digest(password)
       ::Digest::MD5.hexdigest("#{user}:#{realm}:#{password}")
     end
 
+    # Public: Check if the given password is the password of this entry.
     def authenticated?(check_password)
-      hd = ::Digest::MD5.hexdigest("#{user}:#{realm}:#{check_password}")
-      return hd == digest
+      check = calc_digest(check_password)
+      return Algorithm.secure_compare(check, digest)
     end
 
+    # Internal: Returns the key of this entry
     def key
       "#{user}:#{realm}"
     end
 
+    # Internal: Returns the file line for this entry
     def to_s
       "#{user}:#{realm}:#{digest}"
     end

data/lib/htauth/digest_file.rb

@@ -1,21 +1,52 @@
 require 'stringio'
-require 'htauth/errors'
+require 'htauth/error'
 require 'htauth/file'
 require 'htauth/digest_entry'
 
 module HTAuth
-  class DigestFileError < StandardError ; end
+  # Public: An API for managing an 'htdigest' file
+  #
+  # Examples
+  #
+  #   ::HTAuth::DigestFile.open("my.digest") do |df|
+  #     df.has_entry?('myuser', 'myrealm')
+  #     df.add_or_update('someuser', 'myrealm', 'a password')
+  #     df.delete('someolduser', 'myotherrealm')
+  #   end
+  #
   class DigestFile < HTAuth::File
 
+    # Private: The class implementing a single entry in the DigestFile
     ENTRY_KLASS = HTAuth::DigestEntry
 
-    # does the entry the the specified username and realm exist in the file
+    # Public: Checks if the given username / realm combination exists
+    #
+    # username - the username to check
+    # realm    - the realm to check
+    #
+    # Examples
+    #
+    #   digest_file.has_entry?("myuser", "myrealm")
+    #   # => true
+    #
+    # Returns true or false if the username/realm combination is found.
     def has_entry?(username, realm)
       test_entry = DigestEntry.new(username, realm)
       @entries.has_key?(test_entry.key)
     end
 
-    # remove an entry from the file
+    # Public: remove the given username / realm from the file.
+    # The file is not written to disk until #save! is called.
+    #
+    # username - the username to remove
+    # realm    - the realm to remove
+    #
+    # Examples
+    #
+    #   digest_file.delete("myuser", "myrealm")
+    #   digest_file.save!
+    #
+    # Returns nothing
     def delete(username, realm)
       if has_entry?(username, realm) then
         ir = internal_record(username, realm)
@@ -27,7 +58,23 @@ module HTAuth
       nil
     end
 
-    # add or update an entry as appropriate
+    # Public: Add or update username / realm entry with the new password.
+    # This will add a new entry if the username / realm combination does not
+    # exist in the file. If the entry does exist in the file, then the password
+    # of the entry is updated to the new password.
+    #
+    # The file is not written to disk until #save! is called.
+    #
+    # username - the username of the entry
+    # realm    - the realm of the entry
+    # password - the password of the entry
+    #
+    # Examples
+    #
+    #   digest_file.add_or_update("newuser", "realm", "password")
+    #   digest_file.save!
+    #
+    # Returns nothing.
     def add_or_update(username, realm, password)
       if has_entry?(username, realm) then
         update(username, realm, password)
@@ -36,7 +83,19 @@ module HTAuth
       end
     end
 
-    # add an new record.  raises an error if the entry exists.
+    # Public: Add a new record to the file.
+    #
+    # username - the username of the entry
+    # realm    - the realm of the entry
+    # password - the password of the entry
+    #
+    # Examples
+    #
+    #   digest_file.add("newuser", "realm", "password")
+    #   digest_file.save!
+    #
+    # Returns nothing.
+    # Raises DigestFileError if the give username / realm already exists.
     def add(username, realm, password)
       raise DigestFileError, "Unable to add already existing user #{username} in realm #{realm}" if has_entry?(username, realm)
 
@@ -48,7 +107,19 @@ module HTAuth
       return nil
     end
 
-    # update an already existing entry with a new password.  raises an error if the entry does not exist
+    # Public: Updates an existing username / relam entry with a new password
+    #
+    # username - the username of the entry
+    # realm    - the realm of the entry
+    # password - the password of the entry
+    #
+    # Examples
+    #
+    #   digest_file.update("existinguser", "realm", "newpassword")
+    #   digest_file.save!
+    #
+    # Returns nothing
+    # Raises DigestfileError if the username / realm is not found in the file
     def update(username, realm, password)
       raise DigestFileError, "Unable to update non-existent user #{username} in realm #{realm}" unless has_entry?(username, realm)
       ir = internal_record(username, realm)
@@ -58,14 +129,29 @@ module HTAuth
       return nil
     end
 
-    # fetches a copy of an entry from the file.  Updateing the entry returned from fetch will NOT
-    # propogate back to the file.
+    # Public: Returns the given DigestEntry from the file.
+    #
+    # Updating the DigestEntry instance returned by this method will NOT update
+    # the file. To update the file, use #update and #save!
+    #
+    # username - the username of the entry
+    # realm    - the realm of the entry
+    #
+    # Examples
+    #
+    #   entry = digest_file.fetch("myuser", "myrealm")
+    #
+    # Returns a DigestEntry if the entry is found
+    # Returns nil if the entry is not found
     def fetch(username, realm)
       return nil unless has_entry?(username, realm)
       ir = internal_record(username, realm)
       return ir['entry'].dup
     end
 
+    # Internal: returns the class used for each entry
+    #
+    # Returns a Class
     def entry_klass
       ENTRY_KLASS
     end

data/lib/htauth/entry.rb

@@ -1,7 +1,7 @@
 module HTAuth
-
-  # base class from which all entries are derived
+  # Internal: base class from which all entries are derived
   class Entry
+    # Internal: return a new instance of this entry
     def dup
       self.class.from_line(self.to_s)
     end

data/lib/htauth/error.rb

@@ -0,0 +1,18 @@
+#-- 
+# Copyrigth (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details
+#++
+
+module HTAuth
+  class Error < StandardError; end
+
+  class ConsoleError < Error; end
+  class DigestFileError < Error ; end
+  class FileAccessError < Error; end
+  class InvalidDigestEntry < Error; end
+  class InvalidPasswdEntry < Error ; end
+  class PasswordError < Error; end
+  class PasswdFileError < Error ; end
+  class TempFileError < Error; end
+end
+

data/lib/htauth/file.rb

@@ -1,19 +1,55 @@
 require 'stringio'
-require 'htauth/errors'
+require 'htauth/error'
 
 module HTAuth
-  class FileAccessError < StandardError ; end
+  # Internal: A base class for DigestFile and PasswordFile to inherit from.
+  #
+  # This class should not be instantiated directly. You must use DigestFile or
+  # PasswordFile.
   class File
-    ALTER  = "alter"
-    CREATE = "create"
-    STDOUT_FLAG = "-"
+
+    # Public: The mode to pass to #open for updating a file
+    ALTER  = "alter".freeze
+
+    # Public: The mode to pass to #open for creating a new file
+    CREATE = "create".freeze
+
+    # Public: A special 'filename' that may be passed to #open for 'saving' to $stdout
+    STDOUT_FLAG = "-".freeze
 
     attr_reader :filename
     attr_reader :file
 
     class << self
-      # open a file yielding the the file object for use.  The file is saved when 
-      # the block exists, if the file has had alterations made.
+      # Public: The method to use to open a DigestFile or PasswordFile.
+      # Altering a non-existent file is an error. Creating an existing file 
+      # results in a truncation and overwrite of the existing file.
+      #
+      # filename - The name of the file to open
+      # mode     - The mode to open the file this must be either CREATE or
+      #            ALTER. (default: ALTER)
+      #
+      # Yields the instance of DigestFile or PasswordFile that was opened.
+      # The File will be saved at the end of the block if any entries have been
+      # added, updated, or deleted.
+      #
+      # Examples
+      #
+      #   df = ::HTAuth::DigestFile.open("my.digest")
+      #
+      #   ::HTAuth::Digestfile.open("my.digest") do |df|
+      #     # ...
+      #   end
+      #
+      #   pf = ::HTAuth::PasswordFile.open("my.passwd")
+      #
+      #   ::HTAuth::PasswordFile.open("my.passwd") do |pf|
+      #     # ...
+      #   end
+      #
+      # Returns the DigestFile or PasswordFile as appropriate.
+      # Raises FileAccessError if an invalid mode is used.
+      # Raises FileAccessError if ALTERing a non-existent file.
       def open(filename, mode = ALTER) 
         f = self.new(filename, mode)
         if block_given?
@@ -27,10 +63,25 @@ module HTAuth
       end
     end
 
-    # Create or Alter a password file.
+    # Public: Create a new DigestFile or PasswordFile.
+    # Generally you do not need to use this method. Use #open instead.
+    #
+    # Altering a non-existent file is an error. Creating an existing file 
+    # results in a truncation and overwrite of the existing file.
+    #
+    # filename - The name of the file to open
+    # mode     - The mode to open the file this must be either CREATE or
+    #            ALTER. (default: ALTER)
+    #
+    # Examples
+    #
+    #   df = ::HTAuth::DigestFile.open("my.digest")
+    #
+    #   pf = ::HTAuth::PasswordFile.open("my.passwd")
     #
-    # Altering a non-existent file is an error.  Creating an existing file results in
-    # a truncation and overwrite of the existing file.
+    # Returns the DigestFile or PasswordFile as appropriate.
+    # Raises FileAccessError if an invalid mode is used.
+    # Raises FileAccessError if ALTERing a non-existent file.
     def initialize(filename, mode = ALTER)
       @filename   = filename
       @mode       = mode
@@ -51,17 +102,30 @@ module HTAuth
       end
     end
 
-    # return whether or not an alteration to the file has happened
+    # Public: Returns if the file has had any alterations.
+    #
+    # Returns true or false
     def dirty?
       @dirty
     end
 
-    # mark the file as dirty
+    # Public: Explicitly mark the file as having had alterations
+    #
+    # Returns true
     def dirty!
       @dirty = true
     end
 
-    # update the original file with the new contents
+    # Public: Write out the file to filename from #open.
+    # This will write out the whole file at once. If writing to a filesystem
+    # file this overwrites the whole file.
+    #
+    # Example
+    #
+    #     df.save!
+    #
+    # Returns nothing
+    # Raises FileAccessError if there was a problem writing the file
     def save!
       begin
         case filename
@@ -78,7 +142,9 @@ module HTAuth
       end
     end
 
-    # return what should be the contents of the file
+    # Internal: Return the String of the entire file contents
+    #
+    # Returns String
     def contents
       c = StringIO.new
       @lines.each do |l| 
@@ -87,8 +153,12 @@ module HTAuth
       c.string
     end
 
-    # load up entries, keep items in the same order and do not trim out any 
-    # items in the file, like commented out lines or empty space
+    # Internal: Loads all the entries from the file into an internal array.
+    #
+    # This keeps the original lines in one array and all the entries in a
+    # separate structure indexed by key. This allows the file to be written back
+    # out in the same order it was read with the appropriate entries updated or
+    # deleted.
     def load_entries
       @lines   = IO.readlines(@filename)
       @lines.each_with_index do |line,idx|
@@ -98,6 +168,7 @@ module HTAuth
           @entries[entry.key] = v
         end
       end
+      nil
     end
   end
 end