eaton 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28bb3b2bbbe4ecc0ad0b791242d1c9e059a832e5efc056b59b3567a30bf4e0dd
-  data.tar.gz: 243a22e2fc3b36accc7f3b01090a4ce53d8309125b86948d9e84977581c80081
+  metadata.gz: eb4213ff1de1459504fd9aef3ff717e711d4926dcc482af271a5ced054c4dd72
+  data.tar.gz: 5cb7bf81a8fc1cd3cba0d27407f352731bb49a07a22e210b87ddcd6fffe5eb9d
 SHA512:
-  metadata.gz: 81f8dec09135247929258c73eadce8baecd45752dd9026d789b7bfb73a1033afb59fbfa75b40bcef3b7b8bd49c3747833781fda22bf9d1bfd72c01648b2d9492
-  data.tar.gz: 00f421eff32a8cdcac89de7433ec744de4cd85616e069ad6ff9069923904762d687768739860d43354b5775e1d31474502cfb020fa064b8d2f0685012449dbea
+  metadata.gz: 5d64daf3ed46a838ee8e1b0b94501122af4b4124c1c9fe934fab670d504268ccf7809470690d69ce102d4ccfa5cde454e03b9f4585444d54b6ffbe1379d70a18
+  data.tar.gz: 8bb820f4d75d9149196d12da53af22e8b75dbd2521894c9b8cfa6d64d09976f0a72c1a35818553ce5a66203b9aa91d86596a486b915c2df9cd60de28c900a72a

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-09-10
+
+### Added
+- `Client#put` for settings writes; the client could only read, POST and DELETE
+- `Eaton::Network`, mixed into `Client`:
+  - `#ipv4` reports the address, mask, gateway and mode eth0 is running on
+  - `#set_ipv4(address:, subnet_mask:, gateway:)` switches eth0 to a static
+    address. All three are required and a blank one raises `ArgumentError`:
+    the PDU applies them together, and a wrong mask can leave it unreachable.
+
+### Improved
+- Enhanced authentication error handling for expired credentials
+- Added detailed password policy requirements in error messages
+- Improved user guidance for first-time login and password expiration scenarios
+- Error messages now include direct instructions for changing password via web interface
+
 ## [0.1.0] - 2025-01-20
 
 ### Added

data/TODO.md

@@ -0,0 +1,81 @@
+# TODO
+
+## Future Enhancements
+
+### Programmatic Password Change (Issue #1)
+
+**Priority**: Medium
+**Context**: First-time login and password expiration handling
+
+**Problem**:
+Eaton PDUs enforce password expiration policies. When credentials expire, users currently must:
+1. Navigate to the PDU web interface
+2. Manually change the password
+3. Update credentials in their application
+
+This creates friction, especially for:
+- First-time setup (initial default password change)
+- Automated systems that need to handle password rotation
+- Multiple PDU management scenarios
+
+**Proposed Solution**:
+Add programmatic password change capability to the client:
+
+```ruby
+# Ruby API
+client = Eaton::Client.new(
+  host: 'pdu.example.com',
+  username: 'admin',
+  password: 'current_password'
+)
+
+client.change_password(new_password: 'NewSecurePass123!')
+
+# CLI
+eaton change-password \
+  --host pdu.example.com \
+  --username admin \
+  --current-password old_pass \
+  --new-password new_pass
+```
+
+**Implementation Requirements**:
+1. Research Eaton PDU API endpoint for password changes
+2. Implement `change_password` method in `Eaton::Client`
+3. Add password policy validation before attempting change
+4. Create CLI command `eaton change-password`
+5. Handle special case: changing expired credentials
+6. Add comprehensive error handling
+7. Update documentation with password management guide
+8. Add tests for password change functionality
+
+**API Research Needed**:
+- Identify correct REST endpoint (likely `/users/{id}` or `/accounts/{id}`)
+- Determine if special authentication is needed for expired credentials
+- Understand session requirements during password change
+- Check if password history/reuse policies are enforced
+
+**Security Considerations**:
+- Never log passwords
+- Clear old password from memory after use
+- Validate new password against policy before submitting
+- Handle authentication state correctly during transition
+- Consider secure input methods (no command-line password echo)
+
+**Testing Approach**:
+- Mock API responses for password change
+- Test policy validation
+- Test error scenarios (wrong current password, policy violations)
+- Integration test with real PDU (manual, not CI)
+
+**Documentation Updates**:
+- Add password management section to README
+- Include examples for both API and CLI
+- Document password policy requirements
+- Add troubleshooting guide for common scenarios
+
+**Related Files**:
+- `lib/eaton/client.rb` - Add change_password method
+- `lib/eaton/cli.rb` - Add CLI command
+- `spec/*` - Add test coverage
+- `README.md` - Update documentation

data/lib/eaton/client.rb

@@ -11,6 +11,7 @@ module Eaton
     class APIError < StandardError; end
 
     include Power
+    include Network
 
     attr_reader :host, :username, :base_url
 
@@ -39,7 +40,7 @@ module Eaton
         @session = data["session"]
         @token
       else
-        raise AuthenticationError, "Authentication failed: #{response.body}"
+        handle_auth_error(response)
       end
     rescue JSON::ParserError => e
       raise AuthenticationError, "Invalid response from server: #{e.message}"
@@ -68,6 +69,16 @@ module Eaton
       handle_response(execute_request(request))
     end
 
+    def put(path, data = {})
+      authenticate! unless authenticated?
+
+      request = Net::HTTP::Put.new("#{@base_path}#{path}")
+      add_auth_headers(request)
+      request.body = data.to_json
+
+      handle_response(execute_request(request))
+    end
+
     def logout
       return unless authenticated?
 
@@ -83,6 +94,65 @@ module Eaton
 
     private
 
+    def handle_auth_error(response)
+      begin
+        error_data = JSON.parse(response.body)
+
+        # Check for expired credentials error
+        if error_data["code"] == 112 && error_data["description"] =~ /expired/i
+          policy = parse_password_policy(error_data["args"])
+          message = build_expired_credentials_message(policy)
+          raise AuthenticationError, message
+        end
+      rescue JSON::ParserError
+        # Fall through to generic error
+      end
+
+      # Generic authentication error
+      raise AuthenticationError, "Authentication failed: #{response.body}"
+    end
+
+    def parse_password_policy(args)
+      return nil unless args && args.is_a?(Array) && args.length >= 7
+
+      {
+        min_length: args[0],
+        max_length: args[1],
+        require_uppercase: args[2] == 1,
+        require_lowercase: args[3] == 1,
+        require_numbers: args[4] == 1,
+        require_special: args[5] == 1,
+        special_chars: args[6]
+      }
+    end
+
+    def build_expired_credentials_message(policy)
+      message = "Credentials are expired. Please change the password via the PDU web interface.\n\n"
+
+      if policy
+        message += "Password requirements:\n"
+        message += "  - Length: #{policy[:min_length]}-#{policy[:max_length]} characters\n"
+
+        requirements = []
+        requirements << "uppercase letters" if policy[:require_uppercase]
+        requirements << "lowercase letters" if policy[:require_lowercase]
+        requirements << "numbers" if policy[:require_numbers]
+        requirements << "special characters" if policy[:require_special]
+
+        message += "  - Must include: #{requirements.join(', ')}\n" if requirements.any?
+        message += "  - Allowed special characters: #{policy[:special_chars]}\n" if policy[:special_chars]
+        message += "\n"
+      end
+
+      message += "To change password:\n"
+      message += "  1. Navigate to https://#{@host}#{@port == 443 ? '' : ":#{@port}"}\n"
+      message += "  2. Log in with current credentials\n"
+      message += "  3. Follow prompts to change password\n"
+      message += "\nNote: First-time login may require password change before API access is granted."
+
+      message
+    end
+
     def http_connection
       @http_connection ||= begin
         http = Net::HTTP.new(@host, @port)

data/lib/eaton/network.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Eaton
+  # eth0 addressing on the PDU's network management card.
+  module Network
+    ETH0_PATH = "/managers/1/networkService/networkInterfaces/eth0"
+
+    # Current eth0 addressing. :mode is "dhcp client" or "manual"; the address,
+    # subnet_mask and gateway are what the interface is running on right now,
+    # which is what DHCP handed it when the mode is dhcp.
+    def ipv4
+      data = get(ETH0_PATH)
+
+      {
+        mode: data.dig("ipv4", "settings", "mode"),
+        address: data.dig("ipv4", "status", "address"),
+        subnet_mask: data.dig("ipv4", "status", "subnetMask"),
+        gateway: data.dig("ipv4", "status", "gateway")
+      }
+    end
+
+    # Switch eth0 to a static address. All three values are required: the PDU
+    # applies them together, and a wrong mask strands it on the wrong subnet.
+    def set_ipv4(address:, subnet_mask:, gateway:)
+      raise ArgumentError, "address, subnet_mask and gateway are all required" if
+        [address, subnet_mask, gateway].any? { |v| v.to_s.strip.empty? }
+
+      put(ETH0_PATH, ipv4: {
+        settings: {
+          enabled: true,
+          mode: "manual",
+          manual: { address: address, subnetMask: subnet_mask, gateway: gateway }
+        }
+      })
+    end
+  end
+end

data/lib/eaton/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Eaton
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/eaton.rb

@@ -2,6 +2,7 @@
 
 require_relative "eaton/version"
 require_relative "eaton/power"
+require_relative "eaton/network"
 require_relative "eaton/client"
 require_relative "eaton/cli"
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: eaton
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jonathan Siegel
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -29,7 +28,7 @@ description: Comprehensive power monitoring and management for Eaton Rack PDU G4
   detailed metrics (voltage, current, power factor), OAuth2 authentication, and SSH
   tunneling support.
 email:
-- jonathan@example.com
+- "<248302+usiegj00@users.noreply.github.com>"
 executables:
 - eaton
 extensions: []
@@ -39,10 +38,12 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- TODO.md
 - exe/eaton
 - lib/eaton.rb
 - lib/eaton/cli.rb
 - lib/eaton/client.rb
+- lib/eaton/network.rb
 - lib/eaton/power.rb
 - lib/eaton/version.rb
 - sig/pdu_manager.rbs
@@ -55,7 +56,6 @@ metadata:
   bug_tracker_uri: https://github.com/usiegj00/eaton/issues
   changelog_uri: https://github.com/usiegj00/eaton/blob/main/CHANGELOG.md
   documentation_uri: https://github.com/usiegj00/eaton
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,8 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby gem and CLI for managing Eaton Rack PDU G4 devices via REST API
 test_files: []