keeper_secrets_manager 17.1.0 → 17.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a75902de495889b3464731f65dc951d778b7b6cde7be9efd6360fde92da3d7e1
-  data.tar.gz: 0e181c7f3bb27e2e43c57bfaf6690ddd3f0b2ecc7791fb9b62d900c3392ba865
+  metadata.gz: a4bd6d345590ff9f958814a482c10cb18dff351be76d9068f477183baf707d2e
+  data.tar.gz: 452a1bfcf84c267a3e9e6b5eee53f791ea14a2ad276f2fc2ba8b42a763f48e3b
 SHA512:
-  metadata.gz: 35d50e5905926f05914d111465835dbe7996dc1c2de12480b092f9acc0569faab6140bce76811c2c085c5b4ea8875dff5d5f196555de95bd3dafc8c578dba606
-  data.tar.gz: 5425415543c572dcc55029c83c2d37c17d471df72da10da1f4da32bed3661c74f3778e50db91bedad4d76a480c82eb8e2dfd0ef3cc4e249b6d1682c3f68dcfce
+  metadata.gz: 772bfaed3f3376b4e5aad8214fc99685c6168a92391865b83faac03a69d4e44bfd26d7a03d2052cc251fa2b70f1fb0e72a313e250678ddb6ba539dd666b3dfa2
+  data.tar.gz: ddf197159f9d56b79ad8eecf7ae74f2ccc8ccfb5642cc8f4d9dff57046a2f6c753f7cc8bd0e48d659819251fe89852573791aa69894a4bb0741a2dc6ce86fe59

data/CHANGELOG.md

@@ -1,16 +1,79 @@
 # Changelog
 
-## [Unreleased]
+## [17.2.0]
 
 ### Fixed
-- `update_secret` now correctly encrypts record data before sending to server
-- `update_secret` now calls `finalize_secret_update` endpoint to persist changes
-- Local record's revision number is automatically refreshed after successful update
-- Consecutive updates on the same record object now work without manual refetching
-- `download_file` now properly respects SSL certificate verification settings and disables CRL checking
-- `upload_file` now uses correct `add_file` endpoint and includes required `ownerRecordRevision` in payload
-- `create_folder` now properly encrypts folder key with AES-CBC and sets correct parent_uid (nil for root-level folders)
-- Fixed AES-CBC encryption to not double-pad data (OpenSSL handles padding automatically)
+- **KSM-1095**: `update_secret` now calls `complete_transaction` after staging the update, so changes are committed to the server rather than remaining in a staged state indefinitely; works for both `KeeperRecord` objects and plain hash inputs
+- **KSM-1094**: `update_secret` no longer raises `NameError: undefined local variable 'record_uid'` when called with a `KeeperRecord` object; the revision refresh now correctly references `record.uid`
+- **KSM-1096**: `download_thumbnail` no longer raises `NoMethodError` when passed a `KeeperFile` object; `KeeperFile` now exposes a `file_key` attribute and the method dispatches on type before attempting hash access
+- **KSM-824**: `to_h` now always includes `custom` in the V3 API payload, even when the array is empty, matching Commander and Vault behavior
+- **KSM-906**: Added IL5 region mapping (`IL5` → `il5.keepersecurity.us`) to `KEEPER_SERVERS`
+- **KSM-987**: `url_safe_str_to_bytes` and `base64_to_bytes` in `Utils` now raise `Error` when passed `nil`; all Base64 decoding in `core.rb` routes through `Utils`
+- **KSM-1090**: `base64` and `logger` are now declared as explicit runtime dependencies in the gemspec; Ruby 4.0 removed these from the default standard library, so any clean install on Ruby 4.0+ previously raised `LoadError` on `require 'keeper_secrets_manager'`. Also removed a dead `require 'ostruct'` from `dto.rb`.
+- **KSM-1070**: Fixed silent AES-CBC fallback in `decrypt_aes_gcm`: an AES-GCM authentication-tag failure now raises `DecryptionError` immediately rather than retrying decryption as AES-CBC; tampered or wrong-key ciphertext previously could produce output without any error.
+- **KSM-685**: `CreateOptions.subfolder_uid` parameter is now correctly sent to the API when creating records
+- **KSM-686**: Disaster recovery caching with `CachingPostFunction` is now implemented to match other SDKs; API response caching works for both `get_secret` and `get_folders` endpoints, and unused `@cache` and `@cache_expiry` instance variables are removed from `SecretsManager`
+- **KSM-696**: Config storage file is now written with `0600` permissions (owner read/write only), preventing other local users from reading stored credentials
+- **KSM-734**: Fixed notation lookup to deduplicate record shortcuts via `uniq { |r| r.uid }` before the ambiguity check; preserves genuine duplicate-title detection while preventing false ambiguity errors when both an original record and its shortcut are in scope
+- **KSM-1088**: `delete_secret` and `delete_folder` now log an error for each record/folder whose `responseCode` is not `"ok"`, surfacing partial-failure details that were previously silently discarded
+- **KSM-1091**: Invalid `proxy_url` now raises `ArgumentError` at initialization with a descriptive message; a URL with no host previously silently bypassed the proxy, and a fully malformed URL raised `NetworkError` at request time instead
+- **KSM-1098**: `get_value`, `get_totp_code`, and `download_file` in `notation_enhancements` no longer raise `NoMethodError` when passed `nil`, an empty string, or a non-String value; `parse` itself now checks `is_a?(String)` before `empty?` to avoid `NoMethodError` for non-String inputs. `notation_enhancements` is now properly required from the main entry point.
+- Fixed example files to use correct SDK APIs: `09_totp.rb` corrects `Totp` to `TOTP` and `generate()` to `generate_code()`; `01_quick_start.rb` uses the `secret.login` dynamic getter instead of hash access; `10_custom_caching.rb` uses `Utils.bytes_to_base64`
+- Fixed badly anchored regular expression in `test/integration/test_totp.rb` that could cause false positives in test validation
+
+### Added
+- **KSM-906**: `SecretsManager` now accepts the 4-part IL5 one-time token `IL5:clientKey:serverPublicKeyId:serverPublicKey`, registering the supplied EC P-256 server public key (keyId 20, outside the built-in 1–18 table) for ECIES transmission-key wrapping, and persists it as `serverPublicKey` in config so it survives restarts. Adds `server_public_key` / `server_public_key_id` constructor options (precedence: programmatic > token > config), a new `ConfigKeys::KEY_SERVER_PUBLIC_KEY`, malformed-OTT validation, and an actionable error when the backend rejects a configured custom key. Non-IL5 tokens are unchanged.
+- **KSM-1013**: `KeeperRecordLink` (via `KeeperRecord#get_links`) wraps each raw `links` entry with never-raising typed accessors: permission booleans with an `allowedSettings` fallback (top-level wins), AES-256-GCM `get_decrypted_data`/`get_link_data`, and `meta`/`ai_settings`/`jit_settings` settings accessors. Adds a `request_links:` keyword to `get_secrets`. Purely additive; the raw `record.links` list is unchanged.
+- **KSM-883**: On HTTP 403 `{"error":"throttled"}`, `post_query` now retries up to 5 times with exponentially increasing delays (11s, 22s, 44s, 88s, 176s) plus 0–25% jitter (one-sided), honoring `retry_after` from the response when present, and raises `ThrottledError` once retries are exhausted. Replaces the previous fixed 60-second sleep with no backoff, jitter, or retry cap.
+- **KSM-1102**: Added `save(record, transaction_type: nil, links_to_remove: nil)` and `save_with_options(record, update_options)`: non-finalizing update aliases that use the stored record key without re-fetching and do not call `complete_transaction`
+- **KSM-1101**: Added `inflate_field_value(uids, replace_fields)` and `get_inflate_ref_types(field_type)` for field-reference resolution; `addressRef` resolves to address fields, `cardRef` resolves to paymentCard/text/pinCode/address fields with recursive inflate
+- **KSM-1100**: Added `get_notation_results` and `try_get_notation_results`: list-returning notation lookup that always returns `Array[String]`, returns all field values by default (no first-element shortcut), and JSON-serializes complex values
+- **KSM-1099**: Added `create_secret_with_options(create_options, record_data, folders: nil)`: explicit options-based creation that accepts a pre-fetched folders list to avoid an extra `get_folders` network call; `create_secret` is unchanged
+- **KSM-743**: Added transmission public key #18 for Gov Cloud Dev environment support
+- **KSM-687**: Added DTO fields and PAM transaction support for complete SDK parity:
+  - `links` field to `KeeperRecord` for linked records support
+  - `is_editable` field to `KeeperRecord` to check edit permissions
+  - `inner_folder_uid` field to `KeeperRecord` for folder location tracking
+  - `thumbnail_url` and `last_modified` fields to `KeeperFile`
+  - `UpdateOptions` class with `transaction_type` and `links_to_remove` support
+  - `update_secret_with_options` method to support removing file links
+  - `request_links` option to `QueryOptions` for fetching linked records
+  - `download_thumbnail` method for downloading file thumbnails
+  - `expires_on` field to `SecretsManagerResponse`
+  - `complete_transaction(record_uid, rollback: false)` method for PAM rotation workflows
+  - `CompleteTransactionPayload` DTO class for transaction completion
+- **KSM-692**: HTTP proxy support for enterprise environments:
+  - `proxy_url` initialization parameter for explicit proxy configuration
+  - `HTTPS_PROXY` / `https_proxy` environment variable support (automatic detection)
+  - Authenticated proxy support (username:password in URL)
+  - Proxy applies to all HTTP operations (API calls, file downloads, file uploads)
+- **KSM-694**: Convenience methods for improved developer experience:
+  - `upload_file_from_path(owner_record_uid, file_path, file_title: nil)`: upload files directly from disk
+  - `try_get_notation(notation_uri)`: error-safe notation access (returns empty array on error)
+- `KeeperSecretsManager.from_config(config_base64, options = {})`: convenience method for initializing from a base64 config string; complements `from_token()` and `from_file()` and provides parity with the .NET SDK's `GetVaultConfigFromConfigString()` pattern
+- `KeeperSecretsManager::CachingPostFunction`: built-in disaster recovery caching
+- `KeeperSecretsManager::Cache`: file-based cache management (save, load, clear); location configurable via `KSM_CACHE_DIR` environment variable
+- Development console script (`bin/console`) for interactive SDK exploration using Pry REPL
+
+### Changed
+- Documentation: Added Ruby SDK to root repository SDK comparison table
+- **Test Coverage:**
+  - Added 5 new integration test files (test_pam_rotation.rb, test_proxy.rb, test_pam_linked_records.rb, test_caching.rb)
+  - Added 17 unit tests for caching functionality and 27 for new features (CompleteTransactionPayload, QueryOptions, proxy configuration, convenience methods)
+  - Enhanced test_file_operations.rb with thumbnail download and file link removal tests
+- **Mock Infrastructure:** Implemented proper AES-256-GCM encryption in `mock_helper.rb`:
+  - Records now use proper AES-GCM encryption (was Base64 only)
+  - Folders use correct AES-CBC encryption for data
+  - Added transmission key encryption/decryption
+  - Added mock endpoints for transaction completion (finalize_secret_update, rollback_secret_update)
+  - Enabled complete offline testing without config.base64
+- **Example Files:**
+  - Added `11_pam_linked_records.rb`: PAM resources with linked credentials and transaction workflow
+  - Added `12_proxy_usage.rb`: HTTP proxy configuration examples
+  - Updated `06_files.rb`: added `upload_file_from_path` convenience method example
+  - Updated `08_notation.rb`: added `try_get_notation` error-safe notation example
+  - Removed emojis from all example files for professional appearance
+- **Dependencies:** Added base32 gem to test dependencies for TOTP support
 
 ## [17.1.0] - 2025-01-06
 
@@ -22,6 +85,14 @@
 - ECC key generation now correctly returns 32-byte raw private keys (was returning 121-byte DER format)
 - Client version now dynamically uses VERSION constant instead of hardcoded value
 - Fixed Tests
+- `update_secret` now correctly encrypts record data before sending to server
+- `update_secret` now calls `finalize_secret_update` endpoint to persist changes
+- Local record's revision number is automatically refreshed after successful update
+- Consecutive updates on the same record object now work without manual refetching
+- `download_file` now properly respects SSL certificate verification settings and disables CRL checking
+- `upload_file` now uses correct `add_file` endpoint and includes required `ownerRecordRevision` in payload
+- `create_folder` now properly encrypts folder key with AES-CBC and sets correct parent_uid (nil for root-level folders)
+- Fixed AES-CBC encryption to not double-pad data (OpenSSL handles padding automatically)
 
 ## [17.0.4] - 2025-10-20
 
@@ -57,4 +128,6 @@
 
 ### Notes
 - Version 17.0.0 to align with other Keeper SDKs
-- No runtime dependencies (base32 is optional)
+- No runtime dependencies (base32 is optional)
+
+[17.2.0]: https://github.com/Keeper-Security/secrets-manager/compare/ruby-sdk-v17.1.0...ruby-sdk-v17.2.0

data/Gemfile

@@ -4,6 +4,9 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'base32', '~> 0.3' # Required for TOTP support in tests
+  gem 'dotenv', '~> 2.8'
+  gem 'pry', '~> 0.14'
   gem 'rake', '~> 13.0'
   gem 'rspec', '~> 3.12'
   gem 'rubocop', '~> 1.12.0'

data/README.md

@@ -1,305 +1,110 @@
-# 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 3.1+ 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
+## Keeper Secrets Manager Ruby SDK
+
+For more information see our official documentation page https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/ruby-sdk
+
+# Change Log
+
+## 17.2.0 - 2025-11-14
+- KSM-685 - Fixed `CreateOptions.subfolder_uid` parameter API transmission
+- KSM-686 - Implemented disaster recovery caching with `CachingPostFunction`
+- KSM-687 - Added missing DTO fields for complete SDK parity (links, is_editable, inner_folder_uid, thumbnail_url, last_modified, expires_on)
+- KSM-1013 - Added typed linked-credential accessors (`KeeperRecordLink` via `record.get_links`) and a `request_links:` option on `get_secrets`
+- KSM-692 - Added HTTP proxy support for enterprise environments
+- KSM-694 - Added convenience methods (`upload_file_from_path`, `try_get_notation`)
+- KSM-696 - Fixed file permissions for Ruby SDK config files
+- KSM-697 - Comprehensive unit test coverage improvements (+358 tests, 63.3% coverage)
+- KSM-734 - Fixed notation lookup to handle duplicate UIDs from record shortcuts
+- KSM-743 - Added transmission public key #18 for Gov Cloud Dev environment support
+- Added `from_config()` convenience method for base64 config initialization
+- Added `update_secret_with_options()` method for removing file links
+- Added `download_thumbnail()` method for file thumbnails
+- Added development console (`bin/console`) for interactive SDK exploration
+- Fixed example files to use correct SDK APIs
+- Improved mock infrastructure with proper AES-256-GCM encryption
+
+## 17.1.0 - 2025-01-06
+- **BREAKING**: Minimum Ruby version increased to 3.1.0 (from 2.6.0)
+- Fixed ECC key generation to return 32-byte raw private keys
+- Fixed `update_secret` to correctly encrypt and persist changes
+- Fixed `download_file` SSL certificate verification
+- Fixed `upload_file` to use correct endpoint
+- Fixed `create_folder` encryption and parent_uid handling
+
+For full version history, see [CHANGELOG.md](CHANGELOG.md)
+
+# Quick Start
 
 ## 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
+gem install keeper_secrets_manager
 ```
 
-## Quick Start
-
-### Initialize with One-Time Token
+## Basic Usage
 
 ```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
+# Initialize 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!'
+# Get all secrets
+records = secrets_manager.get_secrets
 
-# Set complex fields
-record.set_field('address', {
-  'street1' => '123 Main St',
-  'city' => 'New York',
-  'state' => 'NY',
-  'zip' => '10001'
-})
+# Access secret fields
+record = records.first
+puts "Password: #{record.password}"
 ```
 
-## Notation Support
+## Linked Credentials (PAM)
 
-Access specific field values using Keeper notation:
+PAM records can carry linked credentials. Request them with `request_links: true`, then use the typed `KeeperRecordLink` accessors returned by `record.get_links` (the raw entries remain available on `record.links`):
 
 ```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]")
+records = secrets_manager.get_secrets(request_links: true)
 
-# 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:
+records.each do |record|
+  record.get_links.each do |link|
+    puts "-> #{link.record_uid} (path: #{link.path.inspect})"
 
-```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'
-  )
-]
+    # Permission booleans read allowedSettings when nested (e.g. on "meta" links)
+    puts "  rotation allowed: #{link.allows_rotation?}"
+    puts "  admin user: #{link.admin_user?}"
 
-record = KeeperSecretsManager::Dto::KeeperRecord.new(
-  title: 'Server with Helpers',
-  type: 'login',
-  fields: fields.map(&:to_h)
-)
+    # Encrypted ai_settings / jit_settings decrypt with the owning record's key
+    ai = link.get_ai_settings_data(record.record_key)
+    puts "  ai settings: #{ai.inspect}" if ai
+  end
+end
 ```
 
-## Storage Options
+Accessors never raise — decode or decryption failures return `nil`/`false`.
 
-### In-Memory Storage
-```ruby
-storage = KeeperSecretsManager::Storage::InMemoryStorage.new
-```
+## Proxy Support
 
-### File Storage
-```ruby
-storage = KeeperSecretsManager::Storage::FileStorage.new('keeper_config.json')
-```
+For enterprise environments behind HTTP proxies:
 
-### 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'] }
-  ]
+# Method 1: Explicit proxy_url parameter
+secrets_manager = KeeperSecretsManager.from_file(
+  'keeper_config.json',
+  proxy_url: 'http://proxy.company.com:8080'
 )
 
-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
+# Method 2: Authenticated proxy
+secrets_manager = KeeperSecretsManager.from_file(
+  'keeper_config.json',
+  proxy_url: 'http://username:password@proxy.company.com:8080'
 )
-```
-
-## 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
+# Method 3: HTTPS_PROXY environment variable (recommended)
+# export HTTPS_PROXY=http://proxy.company.com:8080
+secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')
+# Proxy auto-detected from environment
 ```
 
-## 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.
+See `examples/ruby/12_proxy_usage.rb` for complete examples.
 
-## Support
+# Documentation
 
-For support, please visit https://docs.keeper.io/secrets-manager/ or contact sm@keepersecurity.com
+For complete documentation, see: https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/ruby-sdk

data/bin/console

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Interactive console for Keeper Secrets Manager Ruby SDK development
+
+require 'bundler/setup'
+require 'pry'
+
+# Load the SDK from local source
+require_relative '../lib/keeper_secrets_manager'
+
+# Load environment variables if .env exists
+begin
+  require 'dotenv/load'
+  puts "✓ Loaded environment variables from .env"
+rescue LoadError
+  # dotenv not available, skip
+end
+
+# Helper message
+puts "Keeper Secrets Manager Ruby SDK Console"
+puts "=" * 60
+puts "SDK loaded from: #{File.expand_path('../lib/keeper_secrets_manager.rb', __dir__)}"
+puts "Version: #{KeeperSecretsManager::VERSION}"
+puts
+
+if ENV['KSM_CONFIG']
+  puts "Quick start:"
+  puts "  storage = KeeperSecretsManager::Storage::InMemoryStorage.new(ENV['KSM_CONFIG'])"
+  puts "  sm = KeeperSecretsManager.new(config: storage)"
+  puts "  secrets = sm.get_secrets"
+  puts
+  puts "With caching:"
+  puts "  sm = KeeperSecretsManager.new(config: storage, custom_post_function: KeeperSecretsManager::CachingPostFunction)"
+  puts
+else
+  puts "No KSM_CONFIG found in environment"
+  puts "Set it in .env or export it before running"
+  puts
+end
+
+puts "Type 'ls KeeperSecretsManager' to explore the SDK"
+puts "=" * 60
+puts
+
+# Start Pry REPL
+Pry.start

data/keeper_secrets_manager.gemspec

@@ -0,0 +1,36 @@
+require_relative 'lib/keeper_secrets_manager/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'keeper_secrets_manager'
+  spec.version       = KeeperSecretsManager::VERSION
+  spec.authors       = ['Keeper Security']
+  spec.email         = ['sm@keepersecurity.com']
+
+  spec.summary       = 'Keeper Secrets Manager SDK for Ruby'
+  spec.description   = 'Ruby SDK for Keeper Secrets Manager - A zero-knowledge platform for managing and protecting infrastructure secrets'
+  spec.homepage      = 'https://github.com/Keeper-Security/secrets-manager'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/Keeper-Security/secrets-manager'
+  spec.metadata['changelog_uri'] = 'https://github.com/Keeper-Security/secrets-manager/blob/master/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # base64 and logger were default gems through Ruby 3.x; Ruby 4.0 unbundled them.
+  # Both are maintained by the Ruby core team — declaring them makes the implicit explicit.
+  spec.add_runtime_dependency 'base64'
+  spec.add_runtime_dependency 'logger'
+
+  # All development dependencies are in Gemfile
+end