keeper_secrets_manager 17.2.1

data/lib/keeper_secrets_manager/storage.rb

@@ -0,0 +1,254 @@
+require 'json'
+require 'base64'
+require 'fileutils'
+
+module KeeperSecretsManager
+  module Storage
+    # Base storage interface
+    module KeyValueStorage
+      def get_string(_key)
+        raise NotImplementedError, 'Subclass must implement get_string'
+      end
+
+      def save_string(_key, _value)
+        raise NotImplementedError, 'Subclass must implement save_string'
+      end
+
+      def get_bytes(key)
+        data = get_string(key)
+        return nil unless data
+
+        # Handle both standard and URL-safe base64
+        begin
+          # First try standard base64
+          Base64.strict_decode64(data)
+        rescue ArgumentError
+          begin
+            # Try URL-safe base64 with padding
+            padding = 4 - (data.length % 4)
+            padding = 0 if padding == 4
+            Base64.urlsafe_decode64(data + '=' * padding)
+          rescue StandardError => e
+            # Last resort - try with decode64 which is more lenient
+            Base64.decode64(data)
+          end
+        end
+      end
+
+      def save_bytes(key, value)
+        save_string(key, Base64.strict_encode64(value))
+      end
+
+      def delete(_key)
+        raise NotImplementedError, 'Subclass must implement delete'
+      end
+
+      def contains?(key)
+        !get_string(key).nil?
+      end
+    end
+
+    # In-memory storage implementation
+    class InMemoryStorage
+      include KeyValueStorage
+
+      def initialize(config_data = nil)
+        @data = {}
+
+        # Initialize from JSON string, base64 string, or hash
+        if config_data
+          parsed = case config_data
+                   when String
+                     # Check if it's base64 encoded
+                     if is_base64?(config_data)
+                       JSON.parse(Base64.decode64(config_data))
+                     else
+                       JSON.parse(config_data)
+                     end
+                   when Hash
+                     config_data
+                   else
+                     {}
+                   end
+
+          parsed.each { |k, v| @data[k.to_s] = v.to_s }
+        end
+      end
+
+      def get_string(key)
+        @data[key.to_s]
+      end
+
+      def save_string(key, value)
+        @data[key.to_s] = value.to_s
+      end
+
+      def delete(key)
+        @data.delete(key.to_s)
+      end
+
+      def to_h
+        @data.dup
+      end
+
+      def to_json(*args)
+        @data.to_json(*args)
+      end
+
+      private
+
+      def is_base64?(str)
+        # Check if string is valid base64
+        return false if str.nil? || str.empty?
+
+        # Remove whitespace
+        str = str.strip
+
+        # Check if length is multiple of 4 (with padding) or can be padded to multiple of 4
+        # Also check if it only contains base64 characters
+        base64_regex = %r{\A[A-Za-z0-9+/]*={0,2}\z}
+
+        str.match?(base64_regex) && (str.length % 4 == 0 || str.length % 4 == 2 || str.length % 4 == 3)
+      end
+    end
+
+    # File-based storage implementation
+    class FileStorage
+      include KeyValueStorage
+
+      def initialize(filename = 'keeper_config.json')
+        @filename = File.expand_path(filename)
+        @data = {}
+        load_data
+      end
+
+      def get_string(key)
+        @data[key.to_s]
+      end
+
+      def save_string(key, value)
+        @data[key.to_s] = value.to_s
+        save_data
+      end
+
+      def delete(key)
+        @data.delete(key.to_s)
+        save_data
+      end
+
+      private
+
+      def load_data
+        if File.exist?(@filename)
+          begin
+            content = File.read(@filename)
+            # Handle empty files
+            @data = if content.strip.empty?
+                      {}
+                    else
+                      JSON.parse(content)
+                    end
+          rescue JSON::ParserError => e
+            raise Error, "Failed to parse config file: #{e.message}"
+          end
+        end
+      end
+
+      def save_data
+        # Ensure directory exists
+        FileUtils.mkdir_p(File.dirname(@filename))
+
+        # Write atomically to avoid corruption
+        temp_file = "#{@filename}.tmp"
+        # Create temp file with secure permissions (0600)
+        File.open(temp_file, 'w', 0o600) do |f|
+          f.write(JSON.pretty_generate(@data))
+        end
+
+        # Move atomically
+        File.rename(temp_file, @filename)
+
+        # Ensure final file has restrictive permissions (owner read/write only)
+        File.chmod(0o600, @filename)
+      rescue StandardError => e
+        raise Error, "Failed to save config file: #{e.message}"
+      end
+    end
+
+    # Environment-based storage (read-only)
+    class EnvironmentStorage
+      include KeyValueStorage
+
+      def initialize(prefix = 'KSM_')
+        @prefix = prefix
+      end
+
+      def get_string(key)
+        ENV["#{@prefix}#{key.to_s.upcase}"]
+      end
+
+      def save_string(_key, _value)
+        raise Error, 'Environment storage is read-only'
+      end
+
+      def delete(_key)
+        raise Error, 'Environment storage is read-only'
+      end
+    end
+
+    # Cacheable storage wrapper
+    class CachingStorage
+      include KeyValueStorage
+
+      def initialize(base_storage, ttl_seconds = 600)
+        @base_storage = base_storage
+        @ttl_seconds = ttl_seconds
+        @cache = {}
+        @timestamps = {}
+      end
+
+      def get_string(key)
+        key_str = key.to_s
+
+        # Check cache validity
+        return @cache[key_str] if @cache.key?(key_str) && !expired?(key_str)
+
+        # Fetch from base storage
+        value = @base_storage.get_string(key)
+        if value
+          @cache[key_str] = value
+          @timestamps[key_str] = Time.now
+        end
+
+        value
+      end
+
+      def save_string(key, value)
+        key_str = key.to_s
+        @base_storage.save_string(key, value)
+        @cache[key_str] = value.to_s
+        @timestamps[key_str] = Time.now
+      end
+
+      def delete(key)
+        key_str = key.to_s
+        @base_storage.delete(key)
+        @cache.delete(key_str)
+        @timestamps.delete(key_str)
+      end
+
+      def clear_cache
+        @cache.clear
+        @timestamps.clear
+      end
+
+      private
+
+      def expired?(key)
+        return true unless @timestamps[key]
+
+        Time.now - @timestamps[key] > @ttl_seconds
+      end
+    end
+  end
+end

data/lib/keeper_secrets_manager/totp.rb

@@ -0,0 +1,140 @@
+# TOTP (Time-based One-Time Password) implementation
+# Compliant with RFC 6238
+
+require 'base32'
+require 'openssl'
+require 'uri'
+
+module KeeperSecretsManager
+  class TOTP
+    ALGORITHMS = {
+      'SHA1' => OpenSSL::Digest::SHA1,
+      'SHA256' => OpenSSL::Digest::SHA256,
+      'SHA512' => OpenSSL::Digest::SHA512
+    }.freeze
+
+    # Generate a TOTP code
+    # @param secret [String] Base32 encoded secret
+    # @param time [Time] Time to generate code for (default: current time)
+    # @param algorithm [String] Hash algorithm: SHA1, SHA256, or SHA512
+    # @param digits [Integer] Number of digits (6 or 8)
+    # @param period [Integer] Time period in seconds
+    # @return [String] TOTP code
+    def self.generate_code(secret, time: Time.now, algorithm: 'SHA1', digits: 6, period: 30)
+      # Validate inputs
+      raise ArgumentError, "Invalid algorithm: #{algorithm}" unless ALGORITHMS.key?(algorithm)
+      raise ArgumentError, 'Digits must be 6 or 8' unless [6, 8].include?(digits)
+      raise ArgumentError, 'Period must be positive' unless period.positive?
+
+      # Decode base32 secret
+      key = Base32.decode(secret.upcase.tr(' ', ''))
+
+      # Calculate time counter
+      counter = (time.to_i / period).floor
+
+      # Convert counter to 8-byte string (big-endian)
+      counter_bytes = [counter].pack('Q>')
+
+      # Generate HMAC
+      digest = ALGORITHMS[algorithm].new
+      hmac = OpenSSL::HMAC.digest(digest, key, counter_bytes)
+
+      # Extract dynamic binary code
+      offset = hmac[-1].ord & 0x0f
+      code = (hmac[offset].ord & 0x7f) << 24 |
+             (hmac[offset + 1].ord & 0xff) << 16 |
+             (hmac[offset + 2].ord & 0xff) << 8 |
+             (hmac[offset + 3].ord & 0xff)
+
+      # Generate final OTP value
+      otp = code % (10**digits)
+
+      # Pad with leading zeros if necessary
+      otp.to_s.rjust(digits, '0')
+    end
+
+    # Parse TOTP URL (otpauth://totp/...)
+    # @param url [String] TOTP URL
+    # @return [Hash] Parsed components
+    def self.parse_url(url)
+      uri = URI(url)
+
+      raise ArgumentError, 'Invalid TOTP URL scheme' unless uri.scheme == 'otpauth'
+      raise ArgumentError, 'Invalid TOTP URL type' unless uri.host == 'totp'
+
+      # Extract label (issuer:account or just account)
+      path = uri.path[1..-1] # Remove leading /
+      if path.include?(':')
+        issuer, account = path.split(':', 2)
+      else
+        account = path
+        issuer = nil
+      end
+
+      # Parse query parameters
+      params = URI.decode_www_form(uri.query || '').to_h
+
+      {
+        'account' => URI.decode_www_form_component(account || ''),
+        'issuer' => issuer ? URI.decode_www_form_component(issuer) : params['issuer'],
+        'secret' => params['secret'],
+        'algorithm' => params['algorithm'] || 'SHA1',
+        'digits' => (params['digits'] || '6').to_i,
+        'period' => (params['period'] || '30').to_i
+      }
+    end
+
+    # Generate TOTP URL
+    # @param account [String] Account name (e.g., email)
+    # @param secret [String] Base32 encoded secret
+    # @param issuer [String] Service name
+    # @param algorithm [String] Hash algorithm
+    # @param digits [Integer] Number of digits
+    # @param period [Integer] Time period
+    # @return [String] TOTP URL
+    def self.generate_url(account, secret, issuer: nil, algorithm: 'SHA1', digits: 6, period: 30)
+      label = issuer ? "#{issuer}:#{account}" : account
+
+      params = {
+        'secret' => secret,
+        'algorithm' => algorithm,
+        'digits' => digits,
+        'period' => period
+      }
+
+      params['issuer'] = issuer if issuer
+
+      query = URI.encode_www_form(params)
+      "otpauth://totp/#{URI.encode_www_form_component(label)}?#{query}"
+    end
+
+    # Validate a TOTP code
+    # @param secret [String] Base32 encoded secret
+    # @param code [String] Code to validate
+    # @param time [Time] Time to validate against
+    # @param window [Integer] Number of periods to check before/after
+    # @param algorithm [String] Hash algorithm
+    # @param digits [Integer] Number of digits
+    # @param period [Integer] Time period
+    # @return [Boolean] True if code is valid
+    def self.validate_code(secret, code, time: Time.now, window: 1, algorithm: 'SHA1', digits: 6, period: 30)
+      # Check current time and window
+      (-window..window).each do |offset|
+        test_time = time + (offset * period)
+        test_code = generate_code(secret, time: test_time, algorithm: algorithm, digits: digits, period: period)
+
+        return true if test_code == code
+      end
+
+      false
+    end
+
+    # Generate a random secret suitable for TOTP
+    # @param length [Integer] Number of bytes (default: 20 for 160 bits)
+    # @return [String] Base32 encoded secret
+    def self.generate_secret(length: 20)
+      random_bytes = OpenSSL::Random.random_bytes(length)
+      Base32.encode(random_bytes).delete('=')
+    end
+  end
+end

data/lib/keeper_secrets_manager/utils.rb

@@ -0,0 +1,263 @@
+require 'json'
+require 'base64'
+require 'securerandom'
+require 'time'
+
+module KeeperSecretsManager
+  module Utils
+    class << self
+      # Convert string to bytes
+      def string_to_bytes(str)
+        str.b
+      end
+
+      # Convert bytes to string
+      def bytes_to_string(bytes)
+        bytes.force_encoding('UTF-8')
+      end
+
+      # Convert hash/object to JSON string
+      def dict_to_json(obj)
+        JSON.generate(obj)
+      end
+
+      # Parse JSON string to hash
+      def json_to_dict(json_str)
+        JSON.parse(json_str)
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON: #{e.message}"
+      end
+
+      # Base64 encode
+      def bytes_to_base64(bytes)
+        Base64.strict_encode64(bytes)
+      end
+
+      # Base64 decode
+      def base64_to_bytes(str)
+        raise Error, 'base64_to_bytes: received nil' if str.nil?
+        Base64.strict_decode64(str)
+      rescue ArgumentError => e
+        raise Error, "Invalid base64: #{e.message}"
+      end
+
+      # URL-safe base64 encode (with padding)
+      def url_safe_str_to_bytes(str)
+        raise Error, 'url_safe_str_to_bytes: received nil' if str.nil?
+        str += '=' * (4 - str.length % 4) if str.length % 4 != 0
+        Base64.urlsafe_decode64(str)
+      end
+
+      # URL-safe base64 decode (without padding)
+      def bytes_to_url_safe_str(bytes)
+        Base64.urlsafe_encode64(bytes).delete('=')
+      end
+
+      # Generate random bytes
+      def generate_random_bytes(length)
+        SecureRandom.random_bytes(length)
+      end
+
+      # Generate UID (16 random bytes)
+      def generate_uid
+        bytes_to_url_safe_str(generate_random_bytes(16))
+      end
+
+      # Generate UID bytes
+      def generate_uid_bytes
+        generate_random_bytes(16)
+      end
+
+      # Generate a cryptographically secure random password
+      #
+      # @param length [Integer] Total password length (default: 64)
+      # @param lowercase [Integer] Minimum number of lowercase letters (default: 0)
+      # @param uppercase [Integer] Minimum number of uppercase letters (default: 0)
+      # @param digits [Integer] Minimum number of digit characters (default: 0)
+      # @param special_characters [Integer] Minimum number of special characters (default: 0)
+      # @return [String] Generated password
+      # @raise [ArgumentError] If parameters are invalid or minimums exceed length
+      #
+      # @example Generate a default 64-character password
+      #   password = KeeperSecretsManager::Utils.generate_password
+      #   # => "Xk9$mP2...64 chars total"
+      #
+      # @example Generate a 32-character password with specific requirements
+      #   password = KeeperSecretsManager::Utils.generate_password(
+      #     length: 32,
+      #     lowercase: 2,
+      #     uppercase: 2,
+      #     digits: 2,
+      #     special_characters: 2
+      #   )
+      #   # => "aB12$...32 chars with at least 2 of each type"
+      #
+      # @example Use with record update
+      #   record = secrets_manager.get_secrets(['RECORD_UID']).first
+      #   record.password = KeeperSecretsManager::Utils.generate_password(length: 20)
+      #   secrets_manager.update_secret(record)
+      def generate_password(length: 64, lowercase: 0, uppercase: 0, digits: 0, special_characters: 0)
+        # Validate inputs
+        raise ArgumentError, 'Length must be positive' if length <= 0
+        raise ArgumentError, 'Character counts must be non-negative' if [lowercase, uppercase, digits, special_characters].any?(&:negative?)
+
+        total_minimums = lowercase + uppercase + digits + special_characters
+        raise ArgumentError, "Sum of character minimums (#{total_minimums}) cannot exceed password length (#{length})" if total_minimums > length
+
+        # Character sets
+        lowercase_chars = 'abcdefghijklmnopqrstuvwxyz'
+        uppercase_chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+        digit_chars = '0123456789'
+        special_chars = '!@#$%^&*()_+-=[]{}|;:,.<>?'
+
+        # Build password character array
+        password_chars = []
+
+        # Add minimum required characters from each category
+        lowercase.times { password_chars << lowercase_chars[SecureRandom.random_number(lowercase_chars.length)] }
+        uppercase.times { password_chars << uppercase_chars[SecureRandom.random_number(uppercase_chars.length)] }
+        digits.times { password_chars << digit_chars[SecureRandom.random_number(digit_chars.length)] }
+        special_characters.times { password_chars << special_chars[SecureRandom.random_number(special_chars.length)] }
+
+        # Fill remaining length with random characters from all categories
+        remaining = length - total_minimums
+        all_chars = lowercase_chars + uppercase_chars + digit_chars + special_chars
+
+        remaining.times do
+          password_chars << all_chars[SecureRandom.random_number(all_chars.length)]
+        end
+
+        # Shuffle using Fisher-Yates algorithm with SecureRandom for cryptographic security
+        # This ensures minimum characters aren't clustered at the beginning
+        (password_chars.length - 1).downto(1) do |i|
+          j = SecureRandom.random_number(i + 1)
+          password_chars[i], password_chars[j] = password_chars[j], password_chars[i]
+        end
+
+        password_chars.join
+      end
+
+      # Get current time in milliseconds
+      def now_milliseconds
+        (Time.now.to_f * 1000).to_i
+      end
+
+      # Convert string to boolean
+      def strtobool(val)
+        return val if val.is_a?(TrueClass) || val.is_a?(FalseClass)
+
+        val_str = val.to_s.downcase.strip
+        case val_str
+        when 'true', '1', 'yes', 'y', 'on'
+          true
+        when 'false', '0', 'no', 'n', 'off', ''
+          false
+        else
+          raise ArgumentError, "Invalid boolean value: #{val}"
+        end
+      end
+
+      # Check if string is blank
+      def blank?(str)
+        str.nil? || str.strip.empty?
+      end
+
+      # Deep merge hashes
+      def deep_merge(hash1, hash2)
+        hash1.merge(hash2) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+
+      # Convert camelCase to snake_case
+      def camel_to_snake(str)
+        str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
+      end
+
+      # Convert snake_case to camelCase
+      def snake_to_camel(str, capitalize_first = false)
+        str.split('_').map.with_index do |word, i|
+          i == 0 && !capitalize_first ? word : word.capitalize
+        end.join
+      end
+
+      # Safe integer conversion
+      def to_int(val, default = nil)
+        Integer(val)
+      rescue ArgumentError, TypeError
+        default
+      end
+
+      # URL join
+      def url_join(*parts)
+        parts.map { |part| part.to_s.gsub(%r{^/+|/+$}, '') }
+             .reject(&:empty?)
+             .join('/')
+      end
+
+      # Parse server URL from hostname
+      def get_server_url(hostname, use_ssl = true)
+        return nil if blank?(hostname)
+
+        # Remove protocol if present
+        hostname = hostname.sub(%r{^https?://}, '')
+
+        # Build URL
+        protocol = use_ssl ? 'https' : 'http'
+        "#{protocol}://#{hostname}"
+      end
+
+      # Extract region from token or hostname
+      def extract_region(token_or_hostname)
+        # Check if it's a token with region prefix
+        if token_or_hostname&.include?(':')
+          parts = token_or_hostname.split(':')
+          return parts[0].upcase if parts.length >= 2
+        end
+
+        # Check if hostname matches a known region
+        hostname = token_or_hostname.to_s.downcase
+        KeeperGlobals::KEEPER_SERVERS.each do |region, server|
+          return region if hostname.include?(server)
+        end
+
+        # Default to US
+        'US'
+      end
+
+      # Validate UID format
+      def valid_uid?(uid)
+        return false if blank?(uid)
+
+        # UIDs are base64url encoded 16-byte values
+        begin
+          bytes = url_safe_str_to_bytes(uid)
+          bytes.length == 16
+        rescue StandardError
+          false
+        end
+      end
+
+      # Retry with exponential backoff
+      def retry_with_backoff(max_attempts: 3, base_delay: 1, max_delay: 60)
+        attempt = 0
+        begin
+          yield
+        rescue StandardError => e
+          attempt += 1
+          raise e if attempt >= max_attempts
+
+          delay = [base_delay * (2**(attempt - 1)), max_delay].min
+          sleep(delay)
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/keeper_secrets_manager/version.rb

@@ -0,0 +1,3 @@
+module KeeperSecretsManager
+  VERSION = '17.2.1'.freeze
+end

data/lib/keeper_secrets_manager.rb

@@ -0,0 +1,46 @@
+require 'keeper_secrets_manager/version'
+require 'keeper_secrets_manager/errors'
+require 'keeper_secrets_manager/config_keys'
+require 'keeper_secrets_manager/keeper_globals'
+require 'keeper_secrets_manager/utils'
+require 'keeper_secrets_manager/crypto'
+require 'keeper_secrets_manager/storage'
+require 'keeper_secrets_manager/dto'
+require 'keeper_secrets_manager/field_types'
+require 'keeper_secrets_manager/notation'
+require 'keeper_secrets_manager/notation_enhancements'
+require 'keeper_secrets_manager/cache'
+require 'keeper_secrets_manager/core'
+require 'keeper_secrets_manager/folder_manager'
+
+# Optional TOTP support (only load if base32 gem is available)
+begin
+  require 'keeper_secrets_manager/totp'
+rescue LoadError => e
+  # TOTP support not available without base32 gem
+  # This is optional functionality
+end
+
+module KeeperSecretsManager
+  # Main entry point for the SDK
+  def self.new(options = {})
+    Core::SecretsManager.new(options)
+  end
+
+  # Convenience method to create from token
+  def self.from_token(token, options = {})
+    Core::SecretsManager.new(options.merge(token: token))
+  end
+
+  # Convenience method to create from base64 config string
+  def self.from_config(config_base64, options = {})
+    storage = Storage::InMemoryStorage.new(config_base64)
+    Core::SecretsManager.new(options.merge(config: storage))
+  end
+
+  # Convenience method to create from config file
+  def self.from_file(filename, options = {})
+    storage = Storage::FileStorage.new(filename)
+    Core::SecretsManager.new(options.merge(config: storage))
+  end
+end