keeper_secrets_manager 17.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c8972e0c2423186c5359c666369d46c3f4b4e600d2d8043d1d82c9e35415fdb
+  data.tar.gz: f0ce862b79e0d2aab3a5d2f7da349f6f843b6ce3384de6c713427d8d57cd1ab1
+SHA512:
+  metadata.gz: e08af6212050dbe119413eedee86d031e02b8f585c0e43e35e21ef5a5857cc468fdfcb5411039f508b64787521c654edae6d6728fe1f1853488275163cd4a062
+  data.tar.gz: 68be3a8220c8799676410c40f69f9284bf3e19b705d85ff94f27c3764c76cef814d6e9462deef1563a31620da0b6c911227906dcbf26a0abd39f723603e751bb

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.3.8

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [17.0.3] - 2025-06-25
+
+### Changed
+- Cleaned up directory structure
+- Removed development and debug files from distribution
+- Professional gem organization
+
+## [17.0.2] - 2025-06-25
+
+### Security
+- Removed hardcoded credentials from example files
+- Updated all examples to use environment variables or placeholders
+
+## [17.0.1] - 2025-06-25
+
+### Fixed
+- Added missing files to gem package (folder_manager, notation_enhancements, totp)
+
+## [17.0.0] - 2025-06-25
+
+### Added
+- Initial release of Keeper Secrets Manager Ruby SDK
+- Full compatibility with Keeper Secrets Manager API
+- Dynamic record handling with JavaScript-style flexibility
+- Support for all field types (login, password, url, host, etc.)
+- File upload and download capabilities
+- Folder management and hierarchy operations
+- CRUD operations for records and folders
+- Multiple storage backends (file, in-memory, environment, caching)
+- Notation support for field access
+- TOTP support (optional, requires base32 gem)
+- Comprehensive error handling
+- Ruby 2.6+ compatibility
+
+### Security
+- Zero-knowledge encryption using AES-GCM
+- Secure key management
+- SSL certificate verification
+
+### Notes
+- Version 17.0.0 to align with other Keeper SDKs
+- No runtime dependencies (base32 is optional)

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify gem dependencies in keeper_secrets_manager.gemspec
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.12'
+  gem 'rake', '~> 13.0'
+  gem 'simplecov', '~> 0.22'
+  gem 'webmock', '~> 3.18'
+  gem 'rubocop', '~> 1.12.0'
+  gem 'yard', '~> 0.9'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Keeper Security, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,305 @@
+# Keeper Secrets Manager Ruby SDK
+
+The Ruby SDK for Keeper Secrets Manager provides a flexible, dynamic interface for accessing and managing secrets stored in Keeper's zero-knowledge vault.
+
+## Features
+
+- **Ruby 2.7+ Compatible**: Works with Chef, Puppet, and modern Ruby applications
+- **Dynamic Record Handling**: JavaScript-style flexible records with no rigid class hierarchies
+- **Minimal Dependencies**: Uses only Ruby standard library (no external runtime dependencies)
+- **Comprehensive Crypto**: Full encryption/decryption support using OpenSSL
+- **Multiple Storage Options**: In-memory, file-based, environment variables, and caching
+- **Notation Support**: Access specific fields using `keeper://` URI notation
+- **Field Helpers**: Optional convenience methods for common field types
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'keeper_secrets_manager'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install keeper_secrets_manager
+```
+
+## Quick Start
+
+### Initialize with One-Time Token
+
+```ruby
+require 'keeper_secrets_manager'
+
+# Initialize with one-time token
+token = "US:ONE_TIME_TOKEN_HERE"
+secrets_manager = KeeperSecretsManager.from_token(token)
+
+# Retrieve secrets
+records = secrets_manager.get_secrets
+records.each do |record|
+  puts "#{record.title}: #{record.get_field_value_single('login')}"
+end
+```
+
+### Initialize with Existing Configuration
+
+```ruby
+# From config file
+secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')
+
+# From environment (reads KSM_* variables)
+config = KeeperSecretsManager::Storage::EnvironmentStorage.new('KSM_')
+secrets_manager = KeeperSecretsManager.new(config: config)
+```
+
+## Dynamic Record Creation
+
+The Ruby SDK uses a flexible, JavaScript-style approach to records:
+
+```ruby
+# Create record with hash syntax
+record = KeeperSecretsManager::Dto::KeeperRecord.new(
+  title: 'My Server',
+  type: 'login',
+  fields: [
+    { 'type' => 'login', 'value' => ['admin'] },
+    { 'type' => 'password', 'value' => ['SecurePass123!'] },
+    { 'type' => 'url', 'value' => ['https://example.com'] },
+    { 
+      'type' => 'host', 
+      'value' => [{ 'hostName' => '192.168.1.1', 'port' => '22' }],
+      'label' => 'SSH Server'
+    }
+  ],
+  custom: [
+    { 'type' => 'text', 'label' => 'Environment', 'value' => ['Production'] }
+  ]
+)
+
+# Dynamic field access
+puts record.login          # => "admin"
+record.password = 'NewPassword123!'
+
+# Set complex fields
+record.set_field('address', {
+  'street1' => '123 Main St',
+  'city' => 'New York',
+  'state' => 'NY',
+  'zip' => '10001'
+})
+```
+
+## Notation Support
+
+Access specific field values using Keeper notation:
+
+```ruby
+# Get password from record
+password = secrets_manager.get_notation("keeper://RECORD_UID/field/password")
+
+# Get specific property from complex field
+hostname = secrets_manager.get_notation("keeper://RECORD_UID/field/host[hostName]")
+port = secrets_manager.get_notation("keeper://RECORD_UID/field/host[port]")
+
+# Get custom field by label
+env = secrets_manager.get_notation("keeper://RECORD_UID/custom_field/Environment")
+
+# Access by record title
+url = secrets_manager.get_notation("keeper://My Login/field/url")
+```
+
+## Field Type Helpers
+
+Optional convenience methods for creating typed fields:
+
+```ruby
+# Using field helpers
+fields = [
+  KeeperSecretsManager::FieldTypes::Helpers.login('username'),
+  KeeperSecretsManager::FieldTypes::Helpers.password('SecurePass123!'),
+  KeeperSecretsManager::FieldTypes::Helpers.host(
+    hostname: '192.168.1.100',
+    port: 22
+  ),
+  KeeperSecretsManager::FieldTypes::Helpers.name(
+    first: 'John',
+    last: 'Doe',
+    middle: 'Q'
+  )
+]
+
+record = KeeperSecretsManager::Dto::KeeperRecord.new(
+  title: 'Server with Helpers',
+  type: 'login',
+  fields: fields.map(&:to_h)
+)
+```
+
+## Storage Options
+
+### In-Memory Storage
+```ruby
+storage = KeeperSecretsManager::Storage::InMemoryStorage.new
+```
+
+### File Storage
+```ruby
+storage = KeeperSecretsManager::Storage::FileStorage.new('keeper_config.json')
+```
+
+### Environment Variables
+```ruby
+# Reads from KSM_* environment variables (read-only)
+storage = KeeperSecretsManager::Storage::EnvironmentStorage.new('KSM_')
+```
+
+### Caching Storage
+```ruby
+# Wrap any storage with caching (600 second TTL)
+base_storage = KeeperSecretsManager::Storage::FileStorage.new('config.json')
+storage = KeeperSecretsManager::Storage::CachingStorage.new(base_storage, 600)
+```
+
+## CRUD Operations
+
+### Create Record
+```ruby
+record = KeeperSecretsManager::Dto::KeeperRecord.new(
+  title: 'New Record',
+  type: 'login',
+  fields: [
+    { 'type' => 'login', 'value' => ['user'] },
+    { 'type' => 'password', 'value' => ['pass'] }
+  ]
+)
+
+record_uid = secrets_manager.create_secret(record)
+```
+
+### Update Record
+```ruby
+# Get existing record
+record = secrets_manager.get_secret_by_title("My Record")
+
+# Update fields
+record.set_field('password', 'NewPassword123!')
+record.notes = "Updated on #{Time.now}"
+
+# Save changes
+secrets_manager.update_secret(record)
+```
+
+### Delete Records
+```ruby
+# Delete single record
+secrets_manager.delete_secret('RECORD_UID')
+
+# Delete multiple records
+secrets_manager.delete_secret(['UID1', 'UID2', 'UID3'])
+```
+
+### Folder Operations
+```ruby
+# Get all folders
+folders = secrets_manager.get_folders
+
+# Create folder
+folder_uid = secrets_manager.create_folder('New Folder', parent_uid: 'PARENT_UID')
+
+# Update folder
+secrets_manager.update_folder(folder_uid, 'Renamed Folder')
+
+# Delete folder
+secrets_manager.delete_folder(folder_uid, force: true)
+
+# Folder hierarchy features
+fm = secrets_manager.folder_manager
+
+# Build folder tree structure
+tree = fm.build_folder_tree
+
+# Get folder path from root
+path = secrets_manager.get_folder_path(folder_uid)  # "Parent/Child/Grandchild"
+
+# Find folder by name
+folder = secrets_manager.find_folder_by_name("Finance")
+folder = secrets_manager.find_folder_by_name("Finance", parent_uid: "parent_uid")
+
+# Get folder relationships
+ancestors = fm.get_ancestors(folder_uid)    # [parent, grandparent, ...]
+descendants = fm.get_descendants(folder_uid) # [children, grandchildren, ...]
+
+# Print folder tree to console
+fm.print_tree
+```
+
+## Error Handling
+
+```ruby
+begin
+  records = secrets_manager.get_secrets
+rescue KeeperSecretsManager::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue KeeperSecretsManager::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue KeeperSecretsManager::Error => e
+  puts "General error: #{e.message}"
+end
+```
+
+## Configuration
+
+The SDK can be configured through various options:
+
+```ruby
+secrets_manager = KeeperSecretsManager.new(
+  config: storage,
+  hostname: 'keepersecurity.eu',    # EU datacenter
+  verify_ssl_certs: true,           # Verify SSL certificates
+  logger: Logger.new(STDOUT),       # Custom logger
+  log_level: Logger::DEBUG          # Log level
+)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Testing
+
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run unit tests only
+bundle exec rake unit
+
+# Run with coverage
+bundle exec rake coverage
+
+# Run linter
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Keeper-Security/secrets-manager.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.
+
+## Support
+
+For support, please visit https://docs.keeper.io/secrets-manager/ or contact sm@keepersecurity.com

data/Rakefile

@@ -0,0 +1,30 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+desc 'Run unit tests only'
+RSpec::Core::RakeTask.new(:unit) do |t|
+  t.pattern = 'spec/**/unit/*_spec.rb'
+end
+
+desc 'Run integration tests only'
+RSpec::Core::RakeTask.new(:integration) do |t|
+  t.pattern = 'spec/**/integration/*_spec.rb'
+end
+
+desc 'Run all tests with coverage'
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['spec'].invoke
+end
+
+desc 'Run RuboCop'
+task :rubocop do
+  sh 'bundle exec rubocop'
+end
+
+desc 'Run all quality checks'
+task ci: [:rubocop, :spec]

data/examples/basic_usage.rb

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/keeper_secrets_manager'
+
+# Example: Basic usage of Keeper Secrets Manager Ruby SDK
+
+# Method 1: Initialize with one-time token
+# token = "US:ONE_TIME_TOKEN_HERE"
+# secrets_manager = KeeperSecretsManager.from_token(token)
+
+# Method 2: Initialize with existing config
+config = KeeperSecretsManager::Storage::InMemoryStorage.new({
+  'hostname' => 'keepersecurity.com',
+  'clientId' => 'your-client-id',
+  'privateKey' => 'your-private-key-base64',
+  'appKey' => 'your-app-key-base64'
+})
+secrets_manager = KeeperSecretsManager.new(config: config)
+
+# Get all secrets
+begin
+  records = secrets_manager.get_secrets
+  puts "Found #{records.length} records"
+  
+  records.each do |record|
+    puts "\nRecord: #{record.title}"
+    puts "  Type: #{record.type}"
+    puts "  UID: #{record.uid}"
+    
+    # Access fields dynamically
+    if record.get_field('login')
+      puts "  Login: #{record.get_field_value_single('login')}"
+    end
+    
+    if record.get_field('password')
+      puts "  Password: [HIDDEN]"
+    end
+  end
+rescue => e
+  puts "Error: #{e.message}"
+end
+
+# Get specific record by UID
+begin
+  record_uid = "RECORD_UID_HERE"
+  records = secrets_manager.get_secrets([record_uid])
+  
+  if records.any?
+    record = records.first
+    puts "\nRetrieved record: #{record.title}"
+  end
+rescue => e
+  puts "Error retrieving record: #{e.message}"
+end
+
+# Get record by title
+begin
+  record = secrets_manager.get_secret_by_title("My Login")
+  if record
+    puts "\nFound record by title: #{record.uid}"
+    
+    # Access custom fields
+    record.custom.each do |field|
+      puts "  Custom field '#{field['label']}': #{field['value'].first}"
+    end
+  end
+rescue => e
+  puts "Error: #{e.message}"
+end
+
+# Use notation to access specific field values
+begin
+  # Get password field from a record
+  password = secrets_manager.get_notation("keeper://RECORD_UID/field/password")
+  puts "\nPassword from notation: [HIDDEN]"
+  
+  # Get specific property from complex field
+  hostname = secrets_manager.get_notation("keeper://RECORD_UID/field/host[hostName]")
+  puts "Hostname: #{hostname}"
+  
+  # Get custom field
+  custom_value = secrets_manager.get_notation("keeper://RECORD_UID/custom_field/My Label")
+  puts "Custom field value: #{custom_value}"
+rescue => e
+  puts "Notation error: #{e.message}"
+end
+
+# Create a new record
+begin
+  new_record = KeeperSecretsManager::Dto::KeeperRecord.new(
+    title: 'New Server Login',
+    type: 'login',
+    fields: [
+      { 'type' => 'login', 'value' => ['admin'] },
+      { 'type' => 'password', 'value' => ['SecurePass123!'] },
+      { 'type' => 'url', 'value' => ['https://example.com'] },
+      { 'type' => 'host', 
+        'value' => [{ 'hostName' => '192.168.1.100', 'port' => '22' }],
+        'label' => 'SSH Connection' }
+    ],
+    notes: 'Created by Ruby SDK'
+  )
+  
+  # Create the record
+  # record_uid = secrets_manager.create_secret(new_record)
+  # puts "\nCreated new record: #{record_uid}"
+rescue => e
+  puts "Error creating record: #{e.message}"
+end
+
+# Update existing record
+begin
+  # Get record to update
+  record = secrets_manager.get_secret_by_title("Test Record")
+  
+  if record
+    # Update fields
+    record.set_field('password', 'NewPassword123!')
+    record.notes = "Updated at #{Time.now}"
+    
+    # Save changes
+    # secrets_manager.update_secret(record)
+    # puts "\nRecord updated successfully"
+  end
+rescue => e
+  puts "Error updating record: #{e.message}"
+end
+
+# Working with folders
+begin
+  folders = secrets_manager.get_folders
+  puts "\nFound #{folders.length} folders"
+  
+  folders.each do |folder|
+    puts "  Folder: #{folder.name} (#{folder.uid})"
+  end
+rescue => e
+  puts "Error retrieving folders: #{e.message}"
+end

data/examples/config_string_example.rb

@@ -0,0 +1,99 @@
+#!/usr/bin/env ruby
+
+# Add the Ruby SDK to the load path
+
+require_relative '../lib/keeper_secrets_manager'
+require 'json'
+require 'base64'
+
+puts "=== Using Keeper SDK with Config String ==="
+
+# Example 1: JSON config string
+puts "\n1. Using JSON config string"
+puts "-" * 40
+
+# This would come from your secure configuration
+json_config = {
+  "hostname" => "keepersecurity.com",
+  "clientId" => "YOURCLIENTID",
+  "appKey" => "YOURAPPKEYBASE64",
+  "privateKey" => "YOURPRIVATEKEYBASE64",
+  "appOwnerPublicKey" => "YOUROWNERPUBLICKEYBASE64",
+  "serverPublicKeyId" => "7"
+}.to_json
+
+begin
+  # Initialize with JSON string - NO TOKEN NEEDED!
+  storage = KeeperSecretsManager::Storage::InMemoryStorage.new(json_config)
+  sm = KeeperSecretsManager.new(config: storage)
+  puts "✓ Would connect with pre-configured credentials (if real credentials were provided)"
+rescue => e
+  puts "✗ Expected error with dummy credentials: #{e.message}"
+end
+
+# Example 2: Base64 encoded config
+puts "\n2. Using Base64 encoded config"
+puts "-" * 40
+
+# Encode the config as base64 (like KSM_CONFIG environment variable)
+base64_config = Base64.strict_encode64(json_config)
+puts "Base64 config: #{base64_config[0..50]}..."
+
+begin
+  # Initialize with base64 string - NO TOKEN NEEDED!
+  storage = KeeperSecretsManager::Storage::InMemoryStorage.new(base64_config)
+  sm = KeeperSecretsManager.new(config: storage)
+  puts "✓ Would connect with base64 config (if real credentials were provided)"
+rescue => e
+  puts "✗ Expected error with dummy credentials: #{e.message}"
+end
+
+# Example 3: Using environment variable
+puts "\n3. Using KSM_CONFIG environment variable"
+puts "-" * 40
+
+# Set environment variable (normally done outside the script)
+ENV['KSM_CONFIG'] = base64_config
+
+begin
+  # SDK automatically checks for KSM_CONFIG - NO TOKEN OR CONFIG NEEDED!
+  sm = KeeperSecretsManager.new()
+  puts "✓ Would connect with environment variable (if real credentials were provided)"
+rescue => e
+  puts "✗ Expected error with dummy credentials: #{e.message}"
+end
+
+# Example 4: Real workflow - first time with token, then reuse
+puts "\n4. Real workflow example"
+puts "-" * 40
+
+# First time - use token to get credentials
+puts "First connection with token:"
+puts "sm = KeeperSecretsManager.new(token: 'US:YOUR_TOKEN')"
+puts "config_to_save = sm.config.to_json"
+puts "# Save config_to_save securely"
+
+puts "\nSubsequent connections:"
+puts "saved_config = load_from_secure_storage()"
+puts "storage = KeeperSecretsManager::Storage::InMemoryStorage.new(saved_config)"
+puts "sm = KeeperSecretsManager.new(config: storage)  # No token needed!"
+
+# Example 5: What the config looks like
+puts "\n5. Config structure"
+puts "-" * 40
+puts "After successful token authentication, the config contains:"
+puts JSON.pretty_generate({
+  "clientId" => "Base64 encoded client ID (hash of token)",
+  "appKey" => "Base64 encoded AES key for encryption",
+  "privateKey" => "Base64 encoded EC private key (DER format)",
+  "appOwnerPublicKey" => "Base64 encoded public key for record creation",
+  "hostname" => "keepersecurity.com (or other region)",
+  "serverPublicKeyId" => "7 (or other key ID)"
+})
+
+puts "\n" + "=" * 60
+puts "Key Points:"
+puts "- Once you have the config, you never need the token again"
+puts "- Config can be JSON or base64 encoded"
+puts "- Store the config securely - it contains your encryption keys!"
+puts "- The SDK will NOT ask for a token if valid config is provided"