keeper_secrets_manager 17.0.3 → 17.0.4

data/examples/06_files.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+
+# Files Example - Upload and download file attachments
+
+require 'keeper_secrets_manager'
+require 'tempfile'
+
+# Initialize
+config = ENV['KSM_CONFIG'] || 'YOUR_BASE64_CONFIG'
+secrets_manager = KeeperSecretsManager.from_config(config)
+
+puts "=== File Operations Example ==="
+
+# 1. Find records with files
+puts "\n1. Finding records with files..."
+secrets = secrets_manager.get_secrets
+records_with_files = secrets.select { |s| s.files && s.files.any? }
+
+if records_with_files.empty?
+  puts "No records with files found. Upload example will create one."
+else
+  puts "Found #{records_with_files.length} records with files:"
+  records_with_files.each do |record|
+    puts "  - #{record.title}: #{record.files.length} file(s)"
+  end
+end
+
+# 2. Download files
+if records_with_files.any?
+  puts "\n2. Downloading files..."
+  record = records_with_files.first
+  
+  record.files.each do |file|
+    begin
+      # Download the file
+      downloaded = secrets_manager.download_file(file)
+      
+      # Save to disk
+      filename = downloaded['name'] || 'downloaded_file'
+      File.write(filename, downloaded['data'])
+      
+      puts "✓ Downloaded: #{filename} (#{downloaded['size']} bytes)"
+      puts "  Type: #{downloaded['type']}"
+      
+      # Clean up
+      File.delete(filename) if File.exist?(filename)
+      
+    rescue => e
+      puts "✗ Download failed: #{e.message}"
+    end
+  end
+end
+
+# 3. Upload a file
+puts "\n3. Uploading a file..."
+begin
+  # Create a test file
+  test_content = "This is a test file created at #{Time.now}\n"
+  test_content += "It contains some sample data for demonstration.\n"
+  
+  # Create or find a record to attach the file to
+  record = secrets.first || begin
+    # Create a new record if none exist
+    uid = secrets_manager.create_secret({
+      type: 'login',
+      title: 'File Upload Test',
+      fields: [
+        { type: 'login', value: ['test@example.com'] },
+        { type: 'password', value: ['test123'] }
+      ]
+    })
+    secrets_manager.get_secret_by_uid(uid)
+  end
+  
+  puts "Uploading to record: #{record.title}"
+  
+  # Upload the file
+  file_uid = secrets_manager.upload_file(
+    owner_record_uid: record.uid,
+    file_name: 'test_document.txt',
+    file_data: test_content,
+    mime_type: 'text/plain'
+  )
+  
+  puts "✓ Uploaded file with UID: #{file_uid}"
+  
+  # Verify by downloading
+  updated_record = secrets_manager.get_secret_by_uid(record.uid)
+  new_file = updated_record.files.find { |f| f['fileUid'] == file_uid }
+  
+  if new_file
+    downloaded = secrets_manager.download_file(new_file)
+    puts "✓ Verified: #{downloaded['name']}"
+  end
+  
+rescue => e
+  puts "✗ Upload failed: #{e.message}"
+  puts "  Note: File upload requires write permissions"
+end
+
+# 4. Working with different file types
+puts "\n4. File Type Examples:"
+puts "  Text files: .txt, .log, .conf"
+puts "  Documents: .pdf, .doc, .docx"
+puts "  Images: .jpg, .png, .gif"
+puts "  Archives: .zip, .tar.gz"
+puts "  Keys/Certs: .pem, .key, .crt"
+
+# 5. File size considerations
+puts "\n5. File Size Tips:"
+puts "  - Maximum file size depends on your vault settings"
+puts "  - Large files may take time to upload/download"
+puts "  - Consider compression for large text files"
+puts "  - Binary files are handled automatically"
+
+# Example: Upload a certificate file
+puts "\n6. Certificate Upload Example:"
+cert_example = <<~CERT
+  -----BEGIN CERTIFICATE-----
+  MIIDXTCCAkWgAwIBAgIJAKLdQVPy90WJMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
+  ... (certificate content) ...
+  -----END CERTIFICATE-----
+CERT
+
+puts "  # Upload a certificate"
+puts "  file_uid = secrets_manager.upload_file("
+puts "    owner_record_uid: record.uid,"
+puts "    file_name: 'server.crt',"
+puts "    file_data: cert_content,"
+puts "    mime_type: 'application/x-x509-ca-cert'"
+puts "  )"
+
+puts "\n=== Tips ==="
+puts "- Files are attached to records (you need a record first)"
+puts "- File data is encrypted before upload"
+puts "- Download returns decrypted file content"
+puts "- MIME type helps with file handling but is optional"

data/examples/07_folders.rb

@@ -0,0 +1,145 @@
+#!/usr/bin/env ruby
+
+# Folders Example - Organize secrets in folders
+
+require 'keeper_secrets_manager'
+
+# Initialize
+config = ENV['KSM_CONFIG'] || 'YOUR_BASE64_CONFIG'
+secrets_manager = KeeperSecretsManager.from_config(config)
+
+puts "=== Folder Operations Example ==="
+
+# 1. Get all folders
+puts "\n1. Getting all folders..."
+response = secrets_manager.get_secrets(full_response: true)
+folders = response.folders
+
+if folders.empty?
+  puts "No folders found in vault"
+else
+  puts "Found #{folders.length} folders:"
+  folders.each do |folder|
+    puts "  - #{folder.name || folder.uid} (UID: #{folder.uid})"
+  end
+end
+
+# 2. Get folder hierarchy
+puts "\n2. Folder Hierarchy:"
+if folders.any?
+  # Build folder tree
+  folder_tree = secrets_manager.folder_manager.build_folder_tree
+  
+  # Print tree structure
+  secrets_manager.folder_manager.print_tree
+end
+
+# 3. Create a folder
+puts "\n3. Creating a folder..."
+begin
+  folder_name = "Test Folder #{Time.now.strftime('%Y%m%d_%H%M%S')}"
+  
+  # Create at root level
+  folder_uid = secrets_manager.create_folder(folder_name)
+  puts "✓ Created folder: #{folder_name}"
+  puts "  UID: #{folder_uid}"
+  
+  # Create a subfolder
+  subfolder_name = "Subfolder"
+  subfolder_uid = secrets_manager.create_folder(
+    name: subfolder_name,
+    parent_uid: folder_uid
+  )
+  puts "✓ Created subfolder: #{subfolder_name}"
+  
+rescue => e
+  puts "✗ Error creating folder: #{e.message}"
+end
+
+# 4. Move records to folders
+puts "\n4. Organizing records in folders..."
+begin
+  # Get a record to move
+  record = secrets_manager.get_secrets.first
+  
+  if record && defined?(folder_uid)
+    # Move record to folder
+    record.folder_uid = folder_uid
+    secrets_manager.update_secret(record)
+    
+    puts "✓ Moved '#{record.title}' to folder"
+  end
+  
+rescue => e
+  puts "✗ Error moving record: #{e.message}"
+end
+
+# 5. Find folders
+puts "\n5. Finding folders..."
+if folders.any?
+  # Find by name
+  folder = secrets_manager.find_folder_by_name("Test Folder")
+  puts "✓ Found folder by name: #{folder.uid}" if folder
+  
+  # Get folder path
+  if folder
+    path = secrets_manager.get_folder_path(folder.uid)
+    puts "✓ Folder path: #{path}"
+  end
+  
+  # Get folder ancestors
+  ancestors = secrets_manager.folder_manager.get_ancestors(folder.uid) if folder
+  puts "✓ Ancestors: #{ancestors.map(&:name).join(' > ')}" if ancestors&.any?
+end
+
+# 6. List records in a folder
+puts "\n6. Records in folders:"
+response.records.group_by(&:folder_uid).each do |folder_uid, records|
+  folder = folders.find { |f| f.uid == folder_uid }
+  folder_name = folder&.name || folder_uid || 'Root'
+  
+  puts "\n  #{folder_name}:"
+  records.each do |record|
+    puts "    - #{record.title}"
+  end
+end
+
+# 7. Update folder
+puts "\n7. Updating folder..."
+begin
+  if defined?(folder_uid)
+    secrets_manager.update_folder(
+      folder_uid: folder_uid,
+      name: "Updated Test Folder"
+    )
+    puts "✓ Updated folder name"
+  end
+rescue => e
+  puts "✗ Error updating folder: #{e.message}"
+end
+
+# 8. Delete folder
+puts "\n8. Cleanup - Delete test folders..."
+puts "Press Enter to delete test folders (or Ctrl+C to keep them)..."
+gets
+
+begin
+  if defined?(subfolder_uid)
+    secrets_manager.delete_folder(subfolder_uid)
+    puts "✓ Deleted subfolder"
+  end
+  
+  if defined?(folder_uid)
+    secrets_manager.delete_folder(folder_uid, force: true)
+    puts "✓ Deleted folder"
+  end
+rescue => e
+  puts "✗ Error deleting folder: #{e.message}"
+end
+
+puts "\n=== Folder Tips ==="
+puts "- Folders help organize secrets logically"
+puts "- Use folders for environments (Dev, Test, Prod)"
+puts "- Use folders for teams or projects"
+puts "- Folders can be nested for complex hierarchies"
+puts "- Force delete removes folder even with records"

data/examples/08_notation.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+# Notation Example - Using Keeper Notation for quick access
+
+require 'keeper_secrets_manager'
+
+# Initialize
+config = ENV['KSM_CONFIG'] || 'YOUR_BASE64_CONFIG'
+secrets_manager = KeeperSecretsManager.from_config(config)
+
+puts "=== Keeper Notation Example ==="
+
+# Keeper Notation provides a URI-style way to access secrets
+# Format: keeper://<uid_or_title>/field/<field_name>
+#         keeper://<uid_or_title>/file/<file_name>
+#         keeper://<uid_or_title>/custom_field/<label>
+
+puts "\n1. Basic field access:"
+begin
+  # Get by UID
+  secrets = secrets_manager.get_secrets
+  if secrets.any?
+    uid = secrets.first.uid
+    
+    # Get login field
+    login = secrets_manager.get_notation("keeper://#{uid}/field/login")
+    puts "  Login: #{login}"
+    
+    # Get password field
+    password = secrets_manager.get_notation("keeper://#{uid}/field/password")
+    puts "  Password: [hidden]"
+  end
+rescue => e
+  puts "  Error: #{e.message}"
+end
+
+puts "\n2. Access by title:"
+begin
+  # Use record title instead of UID
+  url = secrets_manager.get_notation("keeper://My Website/field/url")
+  puts "  URL: #{url}"
+rescue => e
+  puts "  Note: Create a record titled 'My Website' to see this work"
+end
+
+puts "\n3. Custom field access:"
+begin
+  # Access custom fields by label
+  api_key = secrets_manager.get_notation("keeper://API Server/custom_field/API Key")
+  puts "  API Key: #{api_key}"
+rescue => e
+  puts "  Note: Custom fields are accessed by their label"
+end
+
+puts "\n4. File access:"
+begin
+  # Download file by name
+  file_data = secrets_manager.get_notation("keeper://My Certificates/file/server.crt")
+  puts "  File downloaded: #{file_data.bytesize} bytes"
+rescue => e
+  puts "  Note: Files are accessed by their filename"
+end
+
+puts "\n5. Notation patterns:"
+puts "  - keeper://<record>/field/<field_type>"
+puts "  - keeper://<record>/custom_field/<label>"
+puts "  - keeper://<record>/file/<filename>"
+puts "  - keeper://<record> (returns entire record)"
+
+puts "\n6. Advanced examples:"
+# You can use notation in templates or configuration
+config_template = <<~CONFIG
+  database:
+    host: keeper://Database Server/field/host
+    port: keeper://Database Server/custom_field/Port
+    username: keeper://Database Server/field/login
+    password: keeper://Database Server/field/password
+CONFIG
+
+puts "  Config template example:"
+puts config_template
+
+# Process template (example)
+puts "\n7. Processing notation in strings:"
+text = "Connect to keeper://Web Server/field/url with keeper://Web Server/field/login"
+puts "  Template: #{text}"
+
+# Find and replace notation patterns
+result = text.gsub(/keeper:\/\/[^\/\s]+\/[^\/\s]+\/[^\s]+/) do |notation|
+  begin
+    secrets_manager.get_notation(notation) || notation
+  rescue
+    notation
+  end
+end
+puts "  Processed: #{result}"
+
+puts "\n=== Notation Tips ==="
+puts "- Use UIDs for exact matching (no ambiguity)"
+puts "- Titles are easier to read but must be unique"
+puts "- Notation is great for configuration files"
+puts "- Returns nil if field doesn't exist"
+puts "- Throws exception if record not found"

data/examples/09_totp.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+
+# TOTP Example - Generate Time-based One-Time Passwords
+
+require 'keeper_secrets_manager'
+
+# Initialize
+config = ENV['KSM_CONFIG'] || 'YOUR_BASE64_CONFIG'
+secrets_manager = KeeperSecretsManager.from_config(config)
+
+puts "=== TOTP (2FA) Example ==="
+
+# Note: TOTP functionality requires the 'base32' gem
+# Install with: gem install base32
+
+begin
+  # Check if TOTP is available
+  unless defined?(KeeperSecretsManager::Totp)
+    puts "\nTOTP functionality requires the 'base32' gem."
+    puts "Install it with: gem install base32"
+    puts "\nWithout TOTP, you can still:"
+    puts "- Store TOTP seeds in oneTimeCode fields"
+    puts "- Use external authenticator apps"
+    puts "- Access the seed for manual setup"
+    exit
+  end
+
+  puts "\n1. Finding records with TOTP:"
+  secrets = secrets_manager.get_secrets
+  totp_records = secrets.select do |s|
+    s.fields.any? { |f| f['type'] == 'oneTimeCode' }
+  end
+
+  if totp_records.empty?
+    puts "  No records with TOTP found."
+    
+    # Example of creating a record with TOTP
+    puts "\n2. Example: Creating a record with TOTP"
+    puts "  record_data = {"
+    puts "    type: 'login',"
+    puts "    title: '2FA Example',"
+    puts "    fields: ["
+    puts "      { type: 'login', value: ['user@example.com'] },"
+    puts "      { type: 'password', value: ['password123'] },"
+    puts "      { type: 'oneTimeCode', value: ['JBSWY3DPEHPK3PXP'] }"
+    puts "    ]"
+    puts "  }"
+  else
+    puts "  Found #{totp_records.length} records with TOTP"
+    
+    # Generate TOTP codes
+    puts "\n2. Generating TOTP codes:"
+    totp_records.each do |record|
+      totp_field = record.fields.find { |f| f['type'] == 'oneTimeCode' }
+      if totp_field && totp_field['value']
+        seed = totp_field['value'].first
+        
+        # Generate current code
+        code = KeeperSecretsManager::Totp.generate(seed)
+        puts "  #{record.title}: #{code}"
+        
+        # Show time remaining
+        time_remaining = 30 - (Time.now.to_i % 30)
+        puts "    Valid for: #{time_remaining} seconds"
+      end
+    end
+  end
+
+  puts "\n3. Using TOTP via notation:"
+  if totp_records.any?
+    uid = totp_records.first.uid
+    begin
+      totp_url = secrets_manager.get_notation("keeper://#{uid}/field/oneTimeCode")
+      puts "  TOTP URL: #{totp_url}"
+    rescue => e
+      puts "  Error: #{e.message}"
+    end
+  end
+
+  puts "\n4. TOTP URL format:"
+  puts "  Standard TOTP seeds can be imported from URLs:"
+  puts "  otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example"
+
+  puts "\n5. Manual TOTP setup:"
+  puts "  If base32 gem is not available:"
+  puts "  1. Store the seed in a oneTimeCode field"
+  puts "  2. Use the seed with Google Authenticator or similar"
+  puts "  3. Or install base32 gem for SDK generation"
+
+rescue => e
+  puts "Error: #{e.message}"
+  puts "\nMake sure 'base32' gem is installed for TOTP support"
+end
+
+puts "\n=== TOTP Tips ==="
+puts "- TOTP codes change every 30 seconds"
+puts "- Store TOTP seeds in oneTimeCode fields"
+puts "- Seeds are typically base32 encoded"
+puts "- Compatible with Google Authenticator"
+puts "- Keep TOTP seeds secure like passwords"

data/examples/README.md

@@ -0,0 +1,89 @@
+# Keeper Secrets Manager Ruby SDK Examples
+
+This directory contains examples demonstrating various features of the Keeper Secrets Manager Ruby SDK.
+
+## Prerequisites
+
+1. Set up your configuration using one of these methods:
+   - Token: `export KSM_TOKEN='your_token_here'`
+   - Base64 Config: `export KSM_CONFIG='your_base64_config_here'`
+
+2. Install the SDK:
+   ```bash
+   gem install keeper_secrets_manager
+   ```
+
+## Examples
+
+### 01_quick_start.rb
+Basic connection and simple secret retrieval. Start here if you're new to the SDK.
+
+### 02_authentication.rb
+Different ways to authenticate with Keeper Secrets Manager:
+- Using token authentication
+- Using base64 configuration string
+
+### 03_retrieve_secrets.rb
+Various methods to retrieve secrets:
+- Get all secrets
+- Get by UID
+- Get by title
+- Access specific fields
+- Using Keeper Notation
+
+### 04_create_update_delete.rb
+CRUD operations for managing secrets:
+- Create new records
+- Update existing records
+- Delete records
+- Batch operations tips
+
+### 05_field_types.rb
+Working with different Keeper field types:
+- Standard fields (login, password, URL)
+- Complex fields (name, address, phone)
+- Custom fields
+- Special fields (payment cards, bank accounts)
+
+### 06_files.rb
+File attachment operations:
+- Download files from records
+- Upload files to records
+- Handle different file types
+
+### 07_folders.rb
+Folder management:
+- List folders
+- Create folders and subfolders
+- Move records between folders
+- Get folder hierarchy
+- Delete folders
+
+### 08_notation.rb
+Using Keeper Notation for quick access:
+- Access fields with URI-style notation
+- Use in configuration templates
+- Access custom fields and files
+
+### 09_totp.rb
+Time-based One-Time Passwords (2FA):
+- Generate TOTP codes
+- Store TOTP seeds
+- Integration with authenticator apps
+
+## Running Examples
+
+Each example can be run directly:
+
+```bash
+ruby 01_quick_start.rb
+```
+
+Make sure your environment variables are set before running the examples.
+
+## Security Notes
+
+- Never hardcode credentials in your code
+- Use environment variables for configuration
+- Keep your tokens and configurations secure
+- Don't commit credentials to version control

data/lib/keeper_secrets_manager/version.rb

@@ -1,3 +1,3 @@
 module KeeperSecretsManager
-  VERSION = '17.0.3'.freeze
+  VERSION = '17.0.4'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keeper_secrets_manager
 version: !ruby/object:Gem::Version
-  version: 17.0.3
+  version: 17.0.4
 platform: ruby
 authors:
 - Keeper Security
@@ -21,21 +21,24 @@ files:
 - ".rspec"
 - ".ruby-version"
 - CHANGELOG.md
+- DEVELOPER_SETUP.md
 - Gemfile
 - LICENSE
+- MANUAL_TESTING_GUIDE.md
 - README.md
+- RUBY_SDK_COMPLETE_DOCUMENTATION.md
+- RUBY_SDK_COMPREHENSIVE_SUMMARY.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
+- examples/01_quick_start.rb
+- examples/02_authentication.rb
+- examples/03_retrieve_secrets.rb
+- examples/04_create_update_delete.rb
+- examples/05_field_types.rb
+- examples/06_files.rb
+- examples/07_folders.rb
+- examples/08_notation.rb
+- examples/09_totp.rb
+- examples/README.md
 - lib/keeper_secrets_manager.rb
 - lib/keeper_secrets_manager/config_keys.rb
 - lib/keeper_secrets_manager/core.rb