keeper_secrets_manager 17.0.4 → 17.2.0

data/examples/03_retrieve_secrets.rb

@@ -1,81 +0,0 @@
-#!/usr/bin/env ruby
-
-# Retrieve Secrets Example - Different ways to access your secrets
-
-require 'keeper_secrets_manager'
-
-# Initialize (use your preferred method)
-config = ENV['KSM_CONFIG'] || 'YOUR_BASE64_CONFIG'
-secrets_manager = KeeperSecretsManager.from_config(config)
-
-puts "=== Retrieving Secrets ==="
-
-# 1. Get all secrets
-puts "\n1. Get all secrets:"
-secrets = secrets_manager.get_secrets
-secrets.each do |secret|
-  puts "  - #{secret.title} (UID: #{secret.uid})"
-end
-
-# 2. Get specific secret by UID
-puts "\n2. Get secret by UID:"
-if secrets.any?
-  uid = secrets.first.uid
-  secret = secrets_manager.get_secret_by_uid(uid)
-  puts "  Title: #{secret.title}"
-  puts "  Type: #{secret.type}"
-  puts "  Fields: #{secret.fields.keys.join(', ')}"
-end
-
-# 3. Get secret by title
-puts "\n3. Get secret by title:"
-begin
-  secret = secrets_manager.get_secret_by_title("My Login")
-  puts "  Found: #{secret.title}"
-rescue => e
-  puts "  Not found: #{e.message}"
-end
-
-# 4. Get multiple secrets by UIDs
-puts "\n4. Get multiple secrets:"
-if secrets.length >= 2
-  uids = secrets.first(2).map(&:uid)
-  selected_secrets = secrets_manager.get_secrets(uids)
-  selected_secrets.each do |secret|
-    puts "  - #{secret.title}"
-  end
-end
-
-# 5. Access specific fields
-puts "\n5. Access secret fields:"
-if secrets.any?
-  secret = secrets.first
-  
-  # Common fields
-  puts "  Login: #{secret.fields['login']}" if secret.fields['login']
-  puts "  URL: #{secret.fields['url']}" if secret.fields['url']
-  
-  # Using dynamic field access
-  puts "  Password: #{secret.password}" if secret.respond_to?(:password)
-  
-  # Custom fields
-  secret.custom&.each do |field|
-    puts "  #{field['label']}: #{field['value']}"
-  end
-end
-
-# 6. Using notation to get specific values
-puts "\n6. Using notation:"
-if secrets.any?
-  uid = secrets.first.uid
-  
-  # Get specific field value
-  login = secrets_manager.get_notation("keeper://#{uid}/field/login")
-  puts "  Login via notation: #{login}"
-  
-  # Get by title
-  value = secrets_manager.get_notation("keeper://My Login/field/password")
-  puts "  Password via notation: [hidden]"
-rescue => e
-  puts "  Notation error: #{e.message}"
-end

data/examples/04_create_update_delete.rb

@@ -1,104 +0,0 @@
-#!/usr/bin/env ruby
-
-# CRUD Operations Example - Create, Read, Update, and Delete secrets
-
-require 'keeper_secrets_manager'
-require 'securerandom'
-
-# Initialize
-config = ENV['KSM_CONFIG'] || 'YOUR_BASE64_CONFIG'
-secrets_manager = KeeperSecretsManager.from_config(config)
-
-puts "=== CRUD Operations Example ==="
-
-# 1. CREATE - Add a new secret
-puts "\n1. Creating a new secret..."
-begin
-  # Create a login record
-  new_record = {
-    type: 'login',
-    title: "Test Login #{Time.now.strftime('%Y%m%d_%H%M%S')}",
-    fields: [
-      { type: 'login', value: ['testuser@example.com'] },
-      { type: 'password', value: [SecureRandom.hex(16)] },
-      { type: 'url', value: ['https://example.com'] }
-    ],
-    custom: [
-      { type: 'text', label: 'Environment', value: ['Testing'] }
-    ],
-    notes: 'Created via Ruby SDK example'
-  }
-  
-  # Create the record (optionally in a specific folder)
-  # record_uid = secrets_manager.create_secret(new_record, folder_uid: 'FOLDER_UID')
-  record_uid = secrets_manager.create_secret(new_record)
-  
-  puts "✓ Created record with UID: #{record_uid}"
-  
-  # 2. READ - Retrieve the created secret
-  puts "\n2. Reading the secret..."
-  secret = secrets_manager.get_secret_by_uid(record_uid)
-  puts "✓ Retrieved: #{secret.title}"
-  puts "  Login: #{secret.login}"
-  puts "  URL: #{secret.url}"
-  puts "  Custom field: #{secret.custom.first['value']}" if secret.custom.any?
-  
-  # 3. UPDATE - Modify the secret
-  puts "\n3. Updating the secret..."
-  
-  # Update specific fields
-  secret.password = SecureRandom.hex(20)  # New password
-  secret.url = 'https://updated-example.com'
-  secret.notes = "Updated on #{Time.now}"
-  
-  # Add a new custom field
-  secret.custom ||= []
-  secret.custom << {
-    'type' => 'text',
-    'label' => 'Last Updated',
-    'value' => [Time.now.to_s]
-  }
-  
-  # Save the updates
-  secrets_manager.update_secret(secret)
-  puts "✓ Updated successfully"
-  
-  # Verify the update
-  updated = secrets_manager.get_secret_by_uid(record_uid)
-  puts "  New URL: #{updated.url}"
-  puts "  Notes: #{updated.notes}"
-  
-  # 4. DELETE - Remove the secret
-  puts "\n4. Deleting the secret..."
-  puts "Press Enter to delete the test record..."
-  gets
-  
-  secrets_manager.delete_secret(record_uid)
-  puts "✓ Deleted record: #{record_uid}"
-  
-  # Verify deletion
-  begin
-    secrets_manager.get_secret_by_uid(record_uid)
-    puts "✗ Record still exists!"
-  rescue
-    puts "✓ Confirmed: Record no longer exists"
-  end
-  
-rescue => e
-  puts "Error: #{e.message}"
-  puts "Make sure you have write permissions in your vault"
-end
-
-# Batch operations example
-puts "\n=== Batch Operations ==="
-puts "1. Create multiple records at once"
-puts "2. Update multiple records"
-puts "3. Delete multiple records"
-puts "(See documentation for batch operation examples)"
-
-# Tips
-puts "\n=== Tips ==="
-puts "- Always handle errors when creating/updating/deleting"
-puts "- Use folder_uid parameter to organize secrets"
-puts "- Check permissions if operations fail"
-puts "- Use batch operations for better performance with multiple records"

data/examples/05_field_types.rb

@@ -1,135 +0,0 @@
-#!/usr/bin/env ruby
-
-# Field Types Example - Working with different field types in Keeper
-
-require 'keeper_secrets_manager'
-
-# Initialize
-config = ENV['KSM_CONFIG'] || 'YOUR_BASE64_CONFIG'
-secrets_manager = KeeperSecretsManager.from_config(config)
-
-puts "=== Field Types Example ==="
-
-# Create a record with various field types
-record_data = {
-  type: 'login',
-  title: 'Field Types Demo',
-  fields: [
-    # Standard fields
-    { type: 'login', value: ['user@example.com'] },
-    { type: 'password', value: ['SecurePassword123!'] },
-    { type: 'url', value: ['https://example.com'] },
-    
-    # Complex fields
-    { type: 'name', value: [{ first: 'John', middle: 'Q', last: 'Doe' }] },
-    { type: 'phone', value: [{ number: '555-1234', ext: '567', type: 'Work' }] },
-    { type: 'email', value: ['john.doe@example.com'] },
-    
-    # Address field
-    { 
-      type: 'address',
-      value: [{
-        street1: '123 Main St',
-        street2: 'Suite 100',
-        city: 'New York',
-        state: 'NY',
-        zip: '10001',
-        country: 'US'
-      }]
-    },
-    
-    # Host field (for servers)
-    {
-      type: 'host',
-      value: [{
-        hostName: '192.168.1.100',
-        port: '22'
-      }]
-    },
-    
-    # Security question
-    {
-      type: 'securityQuestion',
-      value: [{
-        question: 'What is your favorite color?',
-        answer: 'Blue'
-      }]
-    },
-    
-    # Bank account
-    {
-      type: 'bankAccount',
-      value: [{
-        accountType: 'Checking',
-        routingNumber: '021000021',
-        accountNumber: '1234567890'
-      }]
-    },
-    
-    # Payment card
-    {
-      type: 'paymentCard',
-      value: [{
-        cardNumber: '4111111111111111',
-        cardExpirationDate: '12/25',
-        cardSecurityCode: '123'
-      }]
-    },
-    
-    # Date field
-    { type: 'date', value: [Time.now.to_i * 1000] }, # milliseconds
-    
-    # Multiline field
-    { type: 'multiline', value: ["Line 1\nLine 2\nLine 3"] }
-  ],
-  
-  # Custom fields
-  custom: [
-    { type: 'text', label: 'Department', value: ['Engineering'] },
-    { type: 'text', label: 'Project', value: ['Secret Management'] },
-    { type: 'secret', label: 'API Key', value: ['sk_test_123456789'] },
-    { type: 'url', label: 'Documentation', value: ['https://docs.example.com'] }
-  ]
-}
-
-# Example: Reading different field types
-puts "\n1. Standard Fields:"
-begin
-  # If you have a record with these fields
-  secret = secrets_manager.get_secrets.first
-  
-  puts "  Login: #{secret.login}" if secret.respond_to?(:login)
-  puts "  Password: [hidden]" if secret.respond_to?(:password)
-  puts "  URL: #{secret.url}" if secret.respond_to?(:url)
-rescue => e
-  puts "  (Create a record with the fields above to see this in action)"
-end
-
-# Example: Complex field access
-puts "\n2. Complex Fields:"
-puts "  Name field: #{record_data[:fields].find { |f| f[:type] == 'name' }[:value].first}"
-puts "  Phone field: #{record_data[:fields].find { |f| f[:type] == 'phone' }[:value].first}"
-puts "  Address field: #{record_data[:fields].find { |f| f[:type] == 'address' }[:value].first}"
-
-# Example: Using field helpers (if available)
-puts "\n3. Field Helpers:"
-puts "  The SDK provides dynamic access to fields:"
-puts "  - secret.login"
-puts "  - secret.password"
-puts "  - secret.url"
-puts "  - secret.notes"
-puts "  - secret.custom"
-
-# Example: TOTP field (requires base32 gem)
-puts "\n4. TOTP Fields:"
-puts "  TOTP fields store the secret key for 2FA"
-puts "  Install 'base32' gem to generate TOTP codes:"
-puts "  - { type: 'oneTimeCode', value: ['JBSWY3DPEHPK3PXP'] }"
-
-# Tips
-puts "\n=== Field Type Tips ==="
-puts "- Use appropriate field types for better UI experience"
-puts "- Complex fields (name, address, etc.) use structured data"
-puts "- Custom fields are flexible for any additional data"
-puts "- File references use fileRef type"
-puts "- Dates are stored as milliseconds since epoch"

data/examples/06_files.rb

@@ -1,137 +0,0 @@
-#!/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

@@ -1,145 +0,0 @@
-#!/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

@@ -1,103 +0,0 @@
-#!/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"