keeper_secrets_manager 17.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 18b1f0bf853bb2239551325dbe053cf29d7ba68d50dadba1a502eefcc175a044
+  data.tar.gz: 90a4d6f1bdc8dd99c9905d2a30717cef9bde0421c9778e49c1cfe2e3bdbdb59c
+SHA512:
+  metadata.gz: 2038821bbaa4a18b683c45415a6a5f5357ac8a8f6cc9eb677b3ad1130c6a34095f63264704af55a18be8e988d8b79eac716e5ca492694c3b2197417ab38fb1c8
+  data.tar.gz: cf9d6aa23e02f7e0878023216c07c36f38fe8fe4ad9c69f2ffe9c8c0748f9a9aca6de03d05a51def7dc4c407dda9ec2e4448481552d756f08f853fd02ec97127

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,139 @@
+# Changelog
+
+## [17.2.1]
+
+### Security
+- **KSM-1193**: `create_secret` now encrypts the record key to the application owner's public key before sending it, matching the other SDKs. Previously the record key was placed in the create payload without that wrap, while the same request carried the record data encrypted under it. All earlier published versions are affected: 17.0.3, 17.0.4, 17.1.0 and 17.2.0; 17.0.0-17.0.2 were never published to RubyGems. A record key cannot be changed after creation, so upgrading protects newly created records only; records created by an earlier version must be re-created to place them under a new key. `create_secret` now also raises an error when the application configuration has no owner public key, instead of continuing without the encryption step.
+
+## [17.2.0]
+
+### Fixed
+- **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]
+
+### Changed
+- **BREAKING**: Minimum Ruby version increased to 3.1.0 (from 2.6.0)
+    - Users on older Ruby versions should upgrade or pin to keeper_secrets_manager <= 17.0.4
+
+### Fixed
+- 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]
+
+### Changed
+- Maintenance release with internal improvements
+
+## [17.0.3]
+
+### Changed
+- Cleaned up directory structure
+- Removed development and debug files from distribution
+
+## [17.0.2]
+
+### Security
+- Updated all examples to use environment variables or placeholders
+
+## [17.0.1]
+
+### Fixed
+- Added missing files to gem package (folder_manager, notation_enhancements, totp)
+
+## [17.0.0]
+
+### Added
+- Initial release of Keeper Secrets Manager Ruby SDK
+- 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)
+
+[17.2.1]: https://github.com/Keeper-Security/secrets-manager/compare/ruby-sdk-v17.2.0...ruby-sdk-v17.2.1
+[17.2.0]: https://github.com/Keeper-Security/secrets-manager/compare/ruby-sdk-v17.1.0...ruby-sdk-v17.2.0

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+# Specify gem dependencies in keeper_secrets_manager.gemspec
+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'
+  gem 'simplecov', '~> 0.22'
+  gem 'webmock', '~> 3.18'
+  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,113 @@
+## 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.1
+- KSM-1193 - Security fix: `create_secret` now encrypts the record key to the application owner's public key before sending it, matching the other SDKs. Earlier versions placed the record key in the create payload without that wrap, while the same request carried the record data encrypted under it. All previously published versions are affected (17.0.3, 17.0.4, 17.1.0, 17.2.0). A record key cannot be changed after creation, so upgrading protects newly created records only; records created by an earlier version must be re-created to place them under a new key. `create_secret` now raises an error if the application configuration has no `appOwnerPublicKey`. This key is only persisted during binding, so an already-bound configuration cannot acquire it after the fact; re-bind with a fresh one-time token, or set the `KSM_APPOWNERPUBLICKEY` environment variable when using the read-only `EnvironmentStorage`.
+
+## 17.2.0
+- 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
+- **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
+
+```bash
+gem install keeper_secrets_manager
+```
+
+## Basic Usage
+
+```ruby
+require 'keeper_secrets_manager'
+
+# Initialize from config file
+secrets_manager = KeeperSecretsManager.from_file('keeper_config.json')
+
+# Get all secrets
+records = secrets_manager.get_secrets
+
+# Access secret fields
+record = records.first
+puts "Password: #{record.password}"
+```
+
+## Linked Credentials (PAM)
+
+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
+records = secrets_manager.get_secrets(request_links: true)
+
+records.each do |record|
+  record.get_links.each do |link|
+    puts "-> #{link.record_uid} (path: #{link.path.inspect})"
+
+    # Permission booleans read allowedSettings when nested (e.g. on "meta" links)
+    puts "  rotation allowed: #{link.allows_rotation?}"
+    puts "  admin user: #{link.admin_user?}"
+
+    # 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
+```
+
+Accessors never raise — decode or decryption failures return `nil`/`false`.
+
+## Proxy Support
+
+For enterprise environments behind HTTP proxies:
+
+```ruby
+# Method 1: Explicit proxy_url parameter
+secrets_manager = KeeperSecretsManager.from_file(
+  'keeper_config.json',
+  proxy_url: 'http://proxy.company.com:8080'
+)
+
+# Method 2: Authenticated proxy
+secrets_manager = KeeperSecretsManager.from_file(
+  'keeper_config.json',
+  proxy_url: 'http://username:password@proxy.company.com:8080'
+)
+
+# 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
+```
+
+See `examples/ruby/12_proxy_usage.rb` for complete examples.
+
+# Documentation
+
+For complete documentation, see: https://docs.keeper.io/secrets-manager/secrets-manager/developer-sdk-library/ruby-sdk

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: %i[rubocop spec]

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/sdk/ruby/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

data/lib/keeper_secrets_manager/cache.rb

@@ -0,0 +1,139 @@
+require 'fileutils'
+
+module KeeperSecretsManager
+  # File-based caching for disaster recovery
+  # Stores encrypted API responses to allow offline access when network is unavailable
+  class Cache
+    # Default cache file location - can be overridden with KSM_CACHE_DIR environment variable
+    def self.cache_file_path
+      cache_dir = ENV['KSM_CACHE_DIR'] || '.'
+      File.join(cache_dir, 'ksm_cache.bin')
+    end
+
+    # Save encrypted cache data (transmission key + encrypted response)
+    def self.save_cache(data)
+      File.open(cache_file_path, 'wb') do |file|
+        file.write(data)
+      end
+    rescue StandardError => e
+      # Silently fail on cache write errors (don't break the app)
+      warn "Failed to write cache: #{e.message}" if ENV['KSM_DEBUG']
+    end
+
+    # Load encrypted cache data
+    def self.get_cached_data
+      return nil unless File.exist?(cache_file_path)
+
+      File.open(cache_file_path, 'rb', &:read)
+    rescue StandardError => e
+      # Silently fail on cache read errors
+      warn "Failed to read cache: #{e.message}" if ENV['KSM_DEBUG']
+      nil
+    end
+
+    # Remove cache file
+    def self.clear_cache
+      File.delete(cache_file_path) if File.exist?(cache_file_path)
+    rescue StandardError => e
+      warn "Failed to delete cache: #{e.message}" if ENV['KSM_DEBUG']
+    end
+
+    # Check if cache file exists
+    def self.cache_exists?
+      File.exist?(cache_file_path)
+    end
+  end
+
+  # Caching post function for disaster recovery
+  # Wraps the normal post_function to save responses and fall back to cache on network failure
+  # Usage: KeeperSecretsManager.new(config: storage, custom_post_function: KeeperSecretsManager::CachingPostFunction)
+  module CachingPostFunction
+    # Post function that caches successful responses and falls back to cache on failure
+    # This matches the pattern used in Python, JavaScript, Java, and .NET SDKs
+    #
+    # @param url [String] The API endpoint URL
+    # @param transmission_key [Dto::TransmissionKey] The transmission key
+    # @param encrypted_payload [Dto::EncryptedPayload] The encrypted payload with signature
+    # @param verify_ssl_certs [Boolean] Whether to verify SSL certificates
+    # @return [Dto::KSMHttpResponse] Response object
+    def self.call(url, transmission_key, encrypted_payload, verify_ssl_certs = true)
+      # Try network request first
+      begin
+        # Call the static post_function
+        response = make_http_request(url, transmission_key, encrypted_payload, verify_ssl_certs)
+
+        # On success, save to cache (transmission key + encrypted response body)
+        if response.success? && response.data
+          cache_data = transmission_key.key + response.data
+          Cache.save_cache(cache_data)
+        end
+
+        response
+      rescue StandardError => e
+        # Network failed - try to load from cache
+        cached_data = Cache.get_cached_data
+
+        if cached_data && cached_data.bytesize > 32
+          # Extract cached transmission key and response data
+          # First 32 bytes are the transmission key, rest is encrypted response
+          cached_transmission_key = cached_data[0...32]
+          cached_response_data = cached_data[32..-1]
+
+          # Update the transmission key to match cached version
+          transmission_key.key = cached_transmission_key
+
+          # Return cached response as if it came from network
+          Dto::KSMHttpResponse.new(
+            status_code: 200,
+            data: cached_response_data
+          )
+        else
+          # No cache available - re-raise the original error
+          raise e
+        end
+      end
+    end
+
+    # Make HTTP request - extracted to be testable
+    # This duplicates some logic from Core::SecretsManager#post_function
+    # because that method is an instance method
+    def self.make_http_request(url, transmission_key, encrypted_payload, verify_ssl_certs)
+      require 'net/http'
+      require 'uri'
+
+      uri = URI(url)
+
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/octet-stream'
+      request['PublicKeyId'] = transmission_key.public_key_id.to_s
+      request['TransmissionKey'] = Utils.bytes_to_base64(transmission_key.encrypted_key)
+      request['Authorization'] = "Signature #{Utils.bytes_to_base64(encrypted_payload.signature)}"
+      request['Content-Length'] = encrypted_payload.encrypted_payload.bytesize.to_s
+      request.body = encrypted_payload.encrypted_payload
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      if verify_ssl_certs
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+        # Set up certificate store with system defaults
+        store = OpenSSL::X509::Store.new
+        store.set_default_paths
+        http.cert_store = store
+      else
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+
+      response = http.request(request)
+
+      Dto::KSMHttpResponse.new(
+        status_code: response.code.to_i,
+        data: response.body,
+        http_response: response
+      )
+    rescue StandardError => e
+      raise NetworkError, "HTTP request failed: #{e.message}"
+    end
+  end
+end

data/lib/keeper_secrets_manager/config_keys.rb

@@ -0,0 +1,29 @@
+module KeeperSecretsManager
+  module ConfigKeys
+    # Configuration key constants (matching other SDKs)
+    KEY_URL                     = 'url'.freeze
+    KEY_CLIENT_ID               = 'clientId'.freeze
+    KEY_CLIENT_KEY              = 'clientKey'.freeze
+    KEY_HOSTNAME                = 'hostname'.freeze
+    KEY_SERVER_PUBLIC_KEY_ID    = 'serverPublicKeyId'.freeze
+    KEY_SERVER_PUBLIC_KEY       = 'serverPublicKey'.freeze
+    KEY_PRIVATE_KEY             = 'privateKey'.freeze
+    KEY_APP_KEY                 = 'appKey'.freeze
+    KEY_OWNER_PUBLIC_KEY        = 'appOwnerPublicKey'.freeze
+    KEY_APP_UID                 = 'appUid'.freeze
+
+    # All valid keys
+    ALL_KEYS = [
+      KEY_URL,
+      KEY_CLIENT_ID,
+      KEY_CLIENT_KEY,
+      KEY_HOSTNAME,
+      KEY_SERVER_PUBLIC_KEY_ID,
+      KEY_SERVER_PUBLIC_KEY,
+      KEY_PRIVATE_KEY,
+      KEY_APP_KEY,
+      KEY_OWNER_PUBLIC_KEY,
+      KEY_APP_UID
+    ].freeze
+  end
+end