keeper_secrets_manager 17.0.3

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,196 @@
+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)
+        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)
+        # Add padding if needed
+        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
+
+      # 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)
+        result = str.split('_').map.with_index do |word, i|
+          i == 0 && !capitalize_first ? word : word.capitalize
+        end.join
+        result
+      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
+          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 => e
+          attempt += 1
+          if attempt >= max_attempts
+            raise e
+          end
+          
+          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.0.3'.freeze
+end

data/lib/keeper_secrets_manager.rb

@@ -0,0 +1,38 @@
+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/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 config file
+  def self.from_file(filename, options = {})
+    storage = Storage::FileStorage.new(filename)
+    Core::SecretsManager.new(options.merge(config: storage))
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: keeper_secrets_manager
+version: !ruby/object:Gem::Version
+  version: 17.0.3
+platform: ruby
+authors:
+- Keeper Security
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-06-25 00:00:00.000000000 Z
+dependencies: []
+description: Ruby SDK for Keeper Secrets Manager - A zero-knowledge platform for managing
+  and protecting infrastructure secrets
+email:
+- sm@keepersecurity.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".ruby-version"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- examples/basic_usage.rb
+- examples/config_string_example.rb
+- examples/debug_secrets.rb
+- examples/demo_list_secrets.rb
+- examples/download_files.rb
+- examples/flexible_records_example.rb
+- examples/folder_hierarchy_demo.rb
+- examples/full_demo.rb
+- examples/my_test_standalone.rb
+- examples/simple_test.rb
+- examples/storage_examples.rb
+- lib/keeper_secrets_manager.rb
+- lib/keeper_secrets_manager/config_keys.rb
+- lib/keeper_secrets_manager/core.rb
+- lib/keeper_secrets_manager/crypto.rb
+- lib/keeper_secrets_manager/dto.rb
+- lib/keeper_secrets_manager/dto/payload.rb
+- lib/keeper_secrets_manager/errors.rb
+- lib/keeper_secrets_manager/field_types.rb
+- lib/keeper_secrets_manager/folder_manager.rb
+- lib/keeper_secrets_manager/keeper_globals.rb
+- lib/keeper_secrets_manager/notation.rb
+- lib/keeper_secrets_manager/notation_enhancements.rb
+- lib/keeper_secrets_manager/storage.rb
+- lib/keeper_secrets_manager/totp.rb
+- lib/keeper_secrets_manager/utils.rb
+- lib/keeper_secrets_manager/version.rb
+homepage: https://github.com/Keeper-Security/secrets-manager
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Keeper-Security/secrets-manager
+  source_code_uri: https://github.com/Keeper-Security/secrets-manager
+  changelog_uri: https://github.com/Keeper-Security/secrets-manager/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Keeper Secrets Manager SDK for Ruby
+test_files: []