rbop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 96e8173b9f7f72075f24e5aab6ff1dd633f3db82ff6837c0b0e7564d7a9c1b34
+  data.tar.gz: d834308421132df4d396f5826a66c98596fee0ca64e90bd9e44882d1a4a1e617
+SHA512:
+  metadata.gz: 56e254f1e31a0f5c43288ab80a959410a2a79fc516e66e28674476b2470831ac5eddafab139fb1d218e1da683414b37dc549a60e16b6095f7b6edb9905dc3405
+  data.tar.gz: 1ea5603a6234a9c458168d594a7752d6d719ae7718e62c62474b55ef2bd250a35e08d11b3fb1c9f417eff246c793776ec98076708555f8d23391242ea74bfacd

data/README.md

@@ -0,0 +1,125 @@
+# Rbop
+
+[![Ruby](https://github.com/timcase/rbop/actions/workflows/ruby.yml/badge.svg)](https://github.com/timcase/rbop/actions/workflows/ruby.yml)
+
+A Ruby gem for seamless integration with the 1Password CLI (`op`). Rbop provides an intuitive, object-oriented interface for retrieving and working with 1Password items, complete with dynamic method access and intelligent type casting.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rbop'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install rbop
+```
+
+## Quick Start
+
+```ruby
+require 'rbop'
+
+# Initialize client with your 1Password account and vault
+client = Rbop::Client.new(
+  account: "my-team.1password.com", 
+  vault: "Personal"
+)
+
+# Retrieve an item by title
+item = client.get(title: "GitHub Login")
+
+# Access top-level properties
+puts item.title          # => "GitHub Login"
+puts item.category       # => "LOGIN"
+puts item.created_at     # => 2023-12-01 10:30:00 UTC (automatically parsed)
+
+# Access field values dynamically
+puts item.username       # => { "label" => "username", "value" => "john.doe" }
+puts item.password       # => { "label" => "password", "value" => "secret123" }
+
+# CamelCase fields are automatically converted to snake_case
+puts item.two_factor_auth # => { "label" => "twoFactorAuth", "value" => "TOTP" }
+
+# Collision handling with field_ prefix when needed
+puts item.url            # => "https://github.com" (top-level field)
+puts item.field_url      # => { "label" => "url", "value" => "backup-url" }
+
+# Get raw hash data
+puts item.to_h           # => Deep copy of all item data
+puts item.as_json        # => Alias for to_h
+```
+
+## Features
+
+### 🔐 Session Management
+- Automatic authentication with 1Password CLI
+- Session token management and environment variable handling
+- Intelligent sign-in detection and retry logic
+
+### 🎯 Flexible Item Selectors
+- **By title**: `client.get(title: "My Login")`
+- **By ID**: `client.get(id: "abc123def456")`
+- **By share URL**: `client.get(url: "https://share.1password.com/s/...")`
+- **By private URL**: `client.get(url: "https://my-team.1password.com/vaults/...")`
+
+### 🚀 Dynamic API Access
+- **Method access**: Access any field as a method (`item.username`, `item.password`)
+- **Bracket access**: String/symbol indifferent (`item["username"]`, `item[:username]`)
+- **Collision handling**: Automatic `field_` prefix when field names conflict with Ruby methods
+- **Enumeration**: Multiple fields with same name get numeric suffixes (`field_class_2`, `field_class_3`)
+- **Case conversion**: CamelCase field labels become snake_case methods (`firstName` → `first_name`)
+
+### ⚡ Intelligent Type Casting
+- **Timestamp parsing**: Automatic conversion of ISO-8601 strings to `Time` objects
+- **Field-level casting**: Timestamps in field values are also converted
+- **Graceful fallback**: Invalid timestamps return original string values
+
+### 🛡️ Data Safety
+- **Deep copying**: `item.to_h` returns a deep copy to prevent mutation
+- **Immutable access**: Original data remains unchanged regardless of modifications to copies
+- **Type preservation**: Non-string values maintain their original types
+
+## Limitations
+
+- **1Password CLI dependency**: Requires the official 1Password CLI (`op`) to be installed and available in PATH
+- **Shell execution**: All operations execute shell commands under the hood
+- **Thread safety**: ⚠️ **Not thread-safe** - session tokens are managed at the class level. Use separate client instances per thread or implement your own synchronization
+- **Error handling**: Shell command failures bubble up as `Rbop::Shell::CommandFailed` exceptions
+- **Authentication scope**: Supports only account-based authentication, not service account tokens
+
+## Requirements
+
+- Ruby 3.1+
+- [1Password CLI (op)](https://developer.1password.com/docs/cli/get-started/) v2.20.0+
+- Valid 1Password account with CLI access
+
+## 1Password CLI Documentation
+
+For more information about the underlying 1Password CLI:
+- [Getting Started Guide](https://developer.1password.com/docs/cli/get-started/)
+- [CLI Reference](https://developer.1password.com/docs/cli/reference/)
+- [Authentication Methods](https://developer.1password.com/docs/cli/authentication/)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/timcase/rbop.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rbop/client.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rbop
+  class Client
+    attr_reader :account, :vault
+
+    def initialize(account:, vault:)
+      @account = account
+      @vault = vault
+      ensure_cli_present
+    end
+
+    def get(title: nil, id: nil, url: nil, vault: nil)
+      # Build kwargs hash with only non-nil values
+      kwargs = {}
+      kwargs[:title] = title if title
+      kwargs[:id] = id if id
+      kwargs[:url] = url if url
+
+      selector = Rbop::Selector.parse(**kwargs)
+      args = build_op_args(selector, vault)
+      args += [ "--format", "json" ]
+      args += [ "--account", @account ]
+
+      cmd = [ "op" ] + args
+
+      begin
+        stdout, _status = Rbop.shell_runner.run(cmd)
+      rescue Rbop::Shell::CommandFailed
+        # If the command failed, assume it's an authentication error and try signing in
+        puts "[DEBUG] Command failed, attempting signin..." if Rbop.debug
+        signin!
+        stdout, _status = Rbop.shell_runner.run(cmd)
+      end
+
+      raw_hash = JSON.parse(stdout)
+      Rbop::Item.new(raw_hash)
+    rescue JSON::ParserError
+      raise JSON::ParserError, "Invalid JSON response from 1Password CLI"
+    end
+
+    def whoami?
+      cmd = "op whoami --format=json"
+      cmd += " --account #{@account}" if @account
+      stdout, _status = Rbop.shell_runner.run(cmd)
+
+      # Parse the response to ensure it's valid
+      data = JSON.parse(stdout)
+      !!(data["user_uuid"] && data["account_uuid"])
+    rescue Rbop::Shell::CommandFailed, JSON::ParserError
+      false
+    end
+
+
+    def signin!
+      # Get the session token
+      stdout, _status = Rbop.shell_runner.run("op signin --account #{@account} --raw")
+      session_token = stdout.strip
+
+      # Set the session token in the environment using the session token itself
+      # The op whoami command with the session token will tell us the user UUID
+      whoami_stdout, _ = Rbop.shell_runner.run("op whoami --format=json --account #{@account} --session #{session_token}")
+      whoami_data = JSON.parse(whoami_stdout)
+      user_uuid = whoami_data["user_uuid"]
+
+      # Set the session token in the correct environment variable
+      ENV["OP_SESSION_#{user_uuid}"] = session_token
+
+      true
+    rescue Rbop::Shell::CommandFailed, JSON::ParserError
+      raise RuntimeError, "1Password sign-in failed"
+    end
+
+    private
+
+    def ensure_signed_in
+      return if whoami?
+      signin!
+    end
+
+    def build_op_args(selector, vault_override = nil)
+      args = [ "item", "get" ]
+
+      case selector[:type]
+      when :title
+        args << selector[:value]
+        args << "--vault"
+        args << (vault_override || @vault)
+      when :id
+        args << "--id"
+        args << selector[:value]
+      when :url_share, :url_private
+        args << "--share-link"
+        args << selector[:value]
+      end
+
+      args
+    end
+
+    def ensure_cli_present
+      _stdout, _status = Rbop.shell_runner.run("op --version")
+    rescue Rbop::Shell::CommandFailed
+      raise RuntimeError, "1Password CLI (op) not found"
+    end
+  end
+end

data/lib/rbop/item.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "active_support/inflector"
+require "time"
+require "set"
+
+module Rbop
+  class Item
+    attr_reader :raw
+
+    # ISO-8601 datetime pattern
+    ISO_8601_REGEX = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+
+    def initialize(raw_hash)
+      @raw = raw_hash
+      @data = deep_dup(raw_hash)
+      @memo = {}
+      @field_methods = {}
+      build_field_methods
+    end
+
+    def to_h
+      deep_dup(@data)
+    end
+
+    alias_method :as_json, :to_h
+
+    def [](key)
+      key_str = key.to_s
+      return @memo[:"[#{key_str}]"] if @memo.key?(:"[#{key_str}]")
+
+      value = @data[key_str]
+      @memo[:"[#{key_str}]"] = cast_value(key_str, value)
+    end
+
+    def method_missing(method_name, *args, &block)
+      if args.empty? && !block_given?
+        method_str = method_name.to_s
+
+        # Check for field methods first
+        if field_info = @field_methods[method_str]
+          field = field_info[:field]
+          # For field methods, we want to return just the value, not the entire field structure
+          if field.is_a?(Hash) && field.key?("value")
+            value = field["value"]
+            return @memo[method_name] ||= cast_value(field_info[:label], value)
+          else
+            return @memo[method_name] ||= field
+          end
+        end
+
+        # Check for top-level data keys
+        if @data.key?(method_str)
+          value = @data[method_str]
+          return @memo[method_name] ||= cast_value(method_str, value)
+        end
+      end
+
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @field_methods.key?(method_name.to_s) || @data.key?(method_name.to_s) || super
+    end
+
+    private
+
+    def cast_value(key, value)
+      return value unless value.is_a?(String)
+
+      # Cast if key ends with _at or value matches ISO-8601 pattern
+      if key.to_s.end_with?("_at") || value.match?(ISO_8601_REGEX)
+        begin
+          Time.parse(value)
+        rescue ArgumentError
+          value  # Return original value if parsing fails
+        end
+      else
+        value
+      end
+    end
+
+    def build_field_methods
+      fields = @data["fields"]
+      return unless fields.is_a?(Array)
+
+      used_method_names = Set.new
+
+      fields.each do |field|
+        next unless field.is_a?(Hash) && field["label"]
+
+        label = field["label"]
+        base_method_name = ActiveSupport::Inflector.underscore(label.gsub(/\s+/, "_"))
+        method_name = base_method_name
+
+        # Check if method name is already used or has collision
+        if used_method_names.include?(method_name) || has_collision?(method_name)
+          method_name = "field_#{base_method_name}"
+
+          # Handle collision enumeration for field_ prefixed names
+          counter = 2
+          while used_method_names.include?(method_name)
+            method_name = "field_#{base_method_name}_#{counter}"
+            counter += 1
+          end
+        end
+
+        used_method_names.add(method_name)
+        @field_methods[method_name] = { field: field, label: label }
+      end
+    end
+
+    def has_collision?(method_name)
+      # Check if method exists in Ruby object hierarchy
+      respond_to?(method_name, true) ||
+      # Check if it collides with top-level data keys
+      @data.key?(method_name) ||
+      # Check if it's a dangerous Ruby method
+      %w[object_id class send].include?(method_name)
+    end
+
+    def deep_dup(obj)
+      case obj
+      when Hash
+        obj.transform_keys(&:to_s).transform_values { |v| deep_dup(v) }
+      when Array
+        obj.map { |v| deep_dup(v) }
+      else
+        obj.dup rescue obj
+      end
+    end
+  end
+end

data/lib/rbop/selector.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rbop
+  module Selector
+    class << self
+      def parse(**kwargs)
+        validate_arguments!(kwargs)
+
+        case kwargs.keys.first
+        when :title
+          { type: :title, value: kwargs[:title] }
+        when :id
+          { type: :id, value: kwargs[:id] }
+        when :url
+          parse_url(kwargs[:url])
+        end
+      end
+
+      private
+
+      def validate_arguments!(kwargs)
+        if kwargs.empty?
+          raise ArgumentError, "Must provide one of: title:, id:, or url:"
+        end
+
+        if kwargs.keys.length > 1
+          raise ArgumentError, "Must provide exactly one of: title:, id:, or url:"
+        end
+
+        unless [ :title, :id, :url ].include?(kwargs.keys.first)
+          raise ArgumentError, "Must provide one of: title:, id:, or url:"
+        end
+      end
+
+      def parse_url(url)
+        if url.start_with?("https://share.1password.com/")
+          { type: :url_share, value: url }
+        elsif url.include?("/open/i?")
+          { type: :url_private, value: url }
+        else
+          raise ArgumentError, "URL must be a valid 1Password share URL or private link"
+        end
+      end
+    end
+  end
+end

data/lib/rbop/shell.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Rbop
+  # Shell runner for executing system commands
+  module Shell
+    # Exception raised when a command fails
+    class CommandFailed < RuntimeError
+      attr_reader :command, :status
+
+      def initialize(command, status)
+        @command = command
+        @status = status
+        super("Command failed with status #{status}: #{command}")
+      end
+    end
+
+    module_function
+
+    # Run a command and return stdout and exit status
+    #
+    # @param cmd [String, Array] Command to execute
+    # @param env [Hash] Environment variables to prepend
+    # @return [Array<String, Integer>] stdout and exit status
+    def run(cmd, env = {})
+      cmd_string = cmd.is_a?(Array) ? shell_escape_array(cmd) : cmd
+
+      # Log command execution if debug mode is enabled
+      if Rbop.debug
+        $stderr.puts "[RBOP DEBUG] Executing: #{cmd_string}"
+        $stderr.puts "[RBOP DEBUG] Environment: #{env.inspect}" unless env.empty?
+      end
+
+      # Merge env into current ENV for the command
+      if env.empty?
+        stdout = `#{cmd_string}`
+      else
+        # Use bash -c to ensure variable expansion works properly
+        env_string = env.map { |k, v| "#{k}='#{v}'" }.join(" ")
+        full_cmd = "#{env_string} bash -c '#{cmd_string}'"
+        $stderr.puts "[RBOP DEBUG] Full command: #{full_cmd}" if Rbop.debug
+        stdout = `#{full_cmd}`
+      end
+
+      status = $?.exitstatus
+
+      # Log results if debug mode is enabled
+      if Rbop.debug
+        $stderr.puts "[RBOP DEBUG] Exit status: #{status}"
+        if stdout.length > 200
+          $stderr.puts "[RBOP DEBUG] Output (truncated): #{stdout[0..200]}..."
+        else
+          $stderr.puts "[RBOP DEBUG] Output: #{stdout}"
+        end
+      end
+
+      if status != 0
+        # For authentication errors, include stderr/stdout in the exception
+        error_output = stdout.empty? ? "" : ": #{stdout}"
+        raise CommandFailed.new("#{cmd_string}#{error_output}", status)
+      end
+
+      [ stdout, status ]
+    end
+
+    def shell_escape_array(cmd_array)
+      Shellwords.join(cmd_array)
+    end
+
+    module_function :shell_escape_array
+  end
+end

data/lib/rbop/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rbop
+  VERSION = "0.1.0"
+end

data/lib/rbop.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "rbop/version"
+require_relative "rbop/shell"
+require_relative "rbop/client"
+require_relative "rbop/selector"
+require_relative "rbop/item"
+
+module Rbop
+  class Error < StandardError; end
+
+  # Module attributes
+  class << self
+    attr_accessor :shell_runner
+    attr_accessor :debug
+  end
+
+  # Set defaults
+  self.shell_runner = Shell
+  self.debug = false
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: rbop
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tim Case
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |-
+  rbop lets any Ruby ≥ 3.0 program pull secrets from 1Password with a single line of code.
+  It shells out to the official op CLI, performs an interactive sign-in when needed
+email:
+- tim@2drops.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rbop.rb
+- lib/rbop/client.rb
+- lib/rbop/item.rb
+- lib/rbop/selector.rb
+- lib/rbop/shell.rb
+- lib/rbop/version.rb
+homepage: https://github.com/timcase/rbop
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby wrapper around the 1Password CLI for effortless secret retrieval in
+  your scripts.
+test_files: []