fripa 0.1.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ff8e5a918933d2c1fd78f075585c5c1d90c90fce2b13e9ad5e01f52882d6826
-  data.tar.gz: 390931635d1f39407fa112ab02c3e4c3ad170b1161f31888d3213ca491a14206
+  metadata.gz: 2ac5a037cb023bb2f087a6d3f6482c4ca8fa8a1e7f7b70d7a01d88e8e7e62db8
+  data.tar.gz: a7f6e6894ee51a0195f4555e482e29752188805c0c908791232bc8fa7db272f0
 SHA512:
-  metadata.gz: 61530519d2a9d935c9c221322ff05ead8445742f9400aeddde5288a25e12f61c6fdbefc89ddd944d163aa2ec7157eaba9c7b0dcd7ccc758d1b898eae7786466e
-  data.tar.gz: ca8616bb8d874dfe0c0c41f84590a2d0883f55412ec235b7a731bc49c486d87e2fcf7d0e3774bfaf26c372190c87a2961c60eb7f15ebab3c261abd77a176d6db
+  metadata.gz: be1d590702cd1e50e0995b6e8b65683c691ec0f03522ff755126645566d7f87cbd7be9c311db970900ee6b28a3931a5563cadd7cae1c9d24d3982b6bea94c3c5
+  data.tar.gz: 9acd2a8785b03cabf3a4902db60efdc6e5c895137759c8371ecf7577ce94f8c37daab75631ed81ea4918cfe795ebf74e23af716fcf3bfbfa3fdde4bd2b3e19d3

data/CHANGELOG.md

@@ -1,5 +1,56 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-15
+
+### Changed
+- **`Fripa::Client.new` no longer connects.** The client logs in on the first call. Wrong credentials now raise `Fripa::AuthenticationError` on the first call, not in `Client.new`. Call `client.login!` to log in at once. Blank credentials still raise `ArgumentError` in `Client.new`.
+- The vault transport certificate is cached per process and server URL, so all clients share it (before: one fetch per client). It is fetched again after a vault call fails.
+
+### Added
+- `Fripa.client`: one client for the account in `config.username` / `config.password`, shared by the process. It is built on first use and again when the configuration changes. `Fripa.reset_client!` forgets the shared client (e.g. between tests).
+- `Fripa::Client#login!` (returns the session cookie) and `#logged_in?`.
+- `Fripa::Client.new(username:, session_cookie:)` builds a client from an earlier session, without a login request. `password` is now optional. Without a password, an expired session raises `Fripa::AuthenticationError`.
+- `Fripa::Client.new` without `username` uses the credentials from the configuration. With a `username`, it never uses the configured password.
+- `Configuration#inspect` does not show the password.
+
+## [0.2.0] - 2026-10-12
+
+### Changed
+- Network errors and timeouts (`Faraday::Error`) now raise `Fripa::ConnectionError`. Responses that are not JSON also raise `Fripa::ConnectionError`.
+- The session cookie keeps only `name=value` pairs. Attributes like `path`, `httponly` and `secure` are no longer sent back.
+- Login and API calls share one HTTP connection.
+- `Fripa::Client#inspect` and `Fripa::Authenticator#inspect` no longer show the password or the session cookie.
+- `scheme` is case-insensitive. An unknown scheme raises `ArgumentError` instead of falling back to HTTP.
+
+### Added
+- `config.raise_on_partial_failure` (default `false`): when `true`, calls that report per-entry failures (e.g. `group_add_member` with an unknown user, or a user that is already a member) raise `Fripa::PartialFailureError` (a `Fripa::ResponseError`). The full `failed` hash is in `#data`.
+- The client logs in again and retries once when the session expires (HTTP 401).
+- `Fripa::Client#batch` sends many commands in one HTTP request.
+- Configuration options: `timeout`, `open_timeout`, `api_version` and `adapter` (e.g. `:net_http_persistent` for keep-alive).
+- `ipa_format:` option for `vault.archive` and `vault.retrieve`, to read and write vaults in the format of the `ipa` CLI.
+- `users.passwd` accepts no current password, so admins can reset the password of another user.
+- RBS signatures in `sig/`.
+
+### Fixed
+- `vault.retrieve` returns `nil` for an empty vault instead of raising `NoMethodError`.
+- The vault resource fetches the KRA transport certificate once per client, not on every archive and retrieve.
+
+## [0.1.4] - 2026-04-16
+
+### Added
+- Vault resource: `add`, `show`, `archive`, `retrieve`, `add_member`, `delete`, with transport encryption (AES-128-CBC session key wrapped with the KRA transport certificate).
+
+## [0.1.3] - 2025-11-26
+
+### Added
+- `Fripa::ResponseError` with `#code`, `#message` and `#data` for errors returned by FreeIPA.
+
 ## [0.1.2] - 2025-11-14
 
 ### Fixed
@@ -20,3 +71,11 @@ Initial release of Fripa - A Ruby client for the FreeIPA JSON-RPC API.
 - Parameter validation for resource methods
 - Full test suite with VCR cassettes
 - Complete API documentation and usage examples
+
+[Unreleased]: https://github.com/renuo/fripa/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/renuo/fripa/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/renuo/fripa/compare/v0.1.4...v0.2.0
+[0.1.4]: https://github.com/renuo/fripa/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/renuo/fripa/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/renuo/fripa/compare/v0.1.0...v0.1.2
+[0.1.0]: https://github.com/renuo/fripa/releases/tag/v0.1.0

data/README.md

@@ -1,5 +1,11 @@
 # Fripa
 
+[![Gem Version](https://badge.fury.io/rb/fripa.svg)](https://rubygems.org/gems/fripa)
+[![CI](https://github.com/renuo/fripa/actions/workflows/main.yml/badge.svg)](https://github.com/renuo/fripa/actions/workflows/main.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org)
+[![Docs](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://rubydoc.info/gems/fripa)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
+
 A Ruby client for the FreeIPA JSON-RPC API.
 
 Docs: [FreeIPA JSON-RPC API](https://freeipa.readthedocs.io/en/latest/api/json-rpc.html)
@@ -74,6 +80,23 @@ Fripa.config.scheme = 'https' # optional
 Fripa.config.verify_ssl = false
 ```
 
+### Advanced options
+
+```ruby
+Fripa.configure do |config|
+  config.timeout = 30                    # read timeout in seconds (default: Faraday default)
+  config.open_timeout = 5                # connect timeout in seconds (default: Faraday default)
+  config.api_version = "2.251"           # FreeIPA API version sent with each call
+  config.adapter = :net_http_persistent  # any Faraday adapter (default: Faraday.default_adapter)
+  config.raise_on_partial_failure = true # raise Fripa::PartialFailureError (default: false)
+end
+```
+
+The default adapter opens a new TCP/TLS connection for every request. If you
+make many calls with one client, a keep-alive adapter is much faster. Add
+`gem "faraday-net_http_persistent"` to your Gemfile and set
+`config.adapter = :net_http_persistent`.
+
 ### Local development example
 
 For local FreeIPA instances running on HTTP:
@@ -91,26 +114,54 @@ end
 
 ### Creating a Client
 
-Create a client instance with user credentials. The client authenticates immediately upon creation:
+#### Service account (shared client)
+
+Put the credentials in the configuration and use `Fripa.client`. It is one
+client for the whole process: it logs in on the first call, keeps the session,
+and logs in again when the session expires. It is built again when the
+configuration changes.
 
 ```ruby
-client = Fripa::Client.new(
-  username: 'your-username',
-  password: 'your-password'
-)
-# Client is now authenticated and ready to use
+Fripa.configure do |config|
+  config.host = 'ipa.example.com'
+  config.username = 'admin'
+  config.password = 'secret'
+end
+
+Fripa.client.users.show('alice')
 ```
 
-If authentication fails, a `Fripa::AuthenticationError` will be raised immediately:
+In tests, call `Fripa.reset_client!` before each test, so no session or test
+double stays from one test to the next.
+
+#### Other accounts
+
+`Fripa::Client.new` creates a client for one account. It does not connect: it
+logs in on the first call. Call `login!` to log in now, for example to check
+credentials. It returns the session cookie.
 
 ```ruby
+client = Fripa::Client.new(username: 'alice', password: 'her-password')
+
 begin
-  client = Fripa::Client.new(username: 'admin', password: 'wrong-password')
+  cookie = client.login!
 rescue Fripa::AuthenticationError => e
   puts "Authentication failed: #{e.message}"
 end
 ```
 
+To skip the login in later requests, build the client from the session cookie
+(e.g. kept in an encrypted session):
+
+```ruby
+client = Fripa::Client.new(username: 'alice', session_cookie: cookie)
+```
+
+A client without a password cannot log in again: when its session expires, it
+raises `Fripa::AuthenticationError`. With a `username`, `Fripa::Client.new`
+never uses the password from the configuration. A client can be shared between
+threads.
+
 ### Making API Calls
 
 #### Using Resource Methods (Recommended)
@@ -143,6 +194,9 @@ client.users.mod("newuser", mail: "newuser@example.com")
 # Change user password
 client.users.passwd("newuser", "NewPassword123", "TempPassword123")
 
+# Reset the password of another user (admin), without the current password
+client.users.passwd("newuser", "NewPassword123")
+
 # Delete a user
 client.users.delete("newuser")
 ```
@@ -181,6 +235,45 @@ client.groups.remove_member_manager("developers", user: ["manager"])
 client.groups.delete("developers")
 ```
 
+##### Vaults
+
+```ruby
+client = Fripa::Client.new(username: 'admin', password: 'secret')
+
+client.vault.add("my-vault", shared: true)
+client.vault.archive("my-vault", data: "secret", shared: true)
+client.vault.retrieve("my-vault", shared: true) # => "secret"
+client.vault.add_member("my-vault", user: ["alice"], shared: true)
+client.vault.delete("my-vault", shared: true)
+```
+
+By default, `archive` stores the raw bytes. The `ipa` CLI stores the data in a
+JSON envelope (`{"data": "<base64>"}`). To share a vault with the `ipa` CLI
+(`ipa vault-archive` / `ipa vault-retrieve`), pass `ipa_format: true`:
+
+```ruby
+client.vault.archive("my-vault", data: "secret", ipa_format: true, shared: true)
+client.vault.retrieve("my-vault", ipa_format: true, shared: true) # => "secret"
+```
+
+The KRA transport certificate is fetched once per process and server, and all
+clients share it (it is public and the same for every account). If the server
+rejects a vault call, the certificate is fetched again on the next call.
+
+#### Batch Calls
+
+Send many commands in one HTTP request:
+
+```ruby
+result = client.batch(
+  ["user_show", ["alice"]],
+  ["group_find", [], { sizelimit: 0 }]
+)
+result.dig("result", "results").each { |r| puts r["error"] || r["result"] }
+```
+
+`batch` does not raise for errors in a single command. Check `error` in each result.
+
 #### Using Raw API Calls
 
 For API methods without a resource wrapper, use the `call` method directly:
@@ -193,7 +286,31 @@ result = client.call("user_find", ["admin"], { all: true })
 puts result.dig("result", "count")
 ```
 
-The client will automatically authenticate if no session exists.
+If the session expires (HTTP 401), the client logs in again and retries the call once.
+
+### Error Handling
+
+All errors inherit from `Fripa::Error`:
+
+| Error | When |
+|---|---|
+| `Fripa::AuthenticationError` | Login fails |
+| `Fripa::ConnectionError` | Network error, timeout, HTTP error status, or a response that is not JSON |
+| `Fripa::ResponseError` | FreeIPA returns an error (`#code`, `#message`, `#data`) |
+| `Fripa::PartialFailureError` | Only with `config.raise_on_partial_failure = true`. A subclass of `ResponseError`. The call succeeds but some entries fail, e.g. `group_add_member` with an unknown user. `#data` has the full `failed` hash |
+
+By default, these per-entry failures do not raise. They stay in the response, in
+`result["result"]["failed"]`. This will change in 1.0.
+
+```ruby
+begin
+  client.groups.add_member("developers", user: ["alice"])
+rescue Fripa::PartialFailureError => e
+  e.data # => {"member" => {"user" => [["alice", "This entry is already a member"]], "group" => []}}
+rescue Fripa::ResponseError => e
+  puts "#{e.code}: #{e.message}"
+end
+```
 
 ## Development
 

data/lib/fripa/authenticator.rb

@@ -7,6 +7,9 @@ module Fripa
   class Authenticator
     LOGIN_PATH = "/ipa/session/login_password"
     CONTENT_TYPE = "application/x-www-form-urlencoded"
+    # Splits a joined Set-Cookie header ("a=1; path=/, b=2") between cookies,
+    # but not inside attributes such as "Expires=Wed, 21 Oct 2026".
+    COOKIE_SEPARATOR = /,\s*(?=[^\s;,=]+=)/
 
     attr_reader :client
 
@@ -20,30 +23,41 @@ module Fripa
 
       raise AuthenticationError, "Login failed: #{response.status}" unless response.success?
 
-      response.headers["set-cookie"]
+      session_cookie(response.headers["set-cookie"])
     end
 
-    private
+    def inspect
+      "#<#{self.class.name} username=#{client.username.inspect}>"
+    end
 
     def validate_credentials!
       raise ArgumentError, "Username cannot be blank" if client.username.to_s.strip.empty?
       raise ArgumentError, "Password cannot be blank" if client.password.to_s.strip.empty?
     end
 
+    private
+
     def perform_login
-      connection.post(LOGIN_PATH) do |request|
+      client.connection.post(LOGIN_PATH) do |request|
         request.headers["Content-Type"] = CONTENT_TYPE
-        request.headers["Referer"] = "#{client.config.base_url}/ipa"
-        request.body = URI.encode_www_form(user: client.username, password: client.password)
+        request.headers["Referer"] = client.referer
+        request.body = login_body
       end
+    rescue Faraday::Error => e
+      raise ConnectionError, "Login failed: #{e.message}"
     end
 
-    def connection
-      @connection ||= Faraday.new(url: client.config.base_url.to_s) do |f|
-        f.request :url_encoded
-        f.adapter Faraday.default_adapter
-        f.ssl.verify = client.config.verify_ssl
-      end
+    def login_body
+      URI.encode_www_form(user: client.username, password: client.password)
+    end
+
+    # Keeps only "name=value" pairs: attributes like path, httponly or secure
+    # must not be sent back in the Cookie header. Returns nil without a
+    # Set-Cookie header, as before (recorded test cassettes often drop it).
+    def session_cookie(header)
+      return nil if header.nil?
+
+      header.split(COOKIE_SEPARATOR).map { |cookie| cookie.split(";").first.to_s.strip }.reject(&:empty?).join("; ")
     end
   end
 end

data/lib/fripa/client.rb

@@ -6,16 +6,24 @@ require "json"
 module Fripa
   class Client
     API_PATH = "/ipa/session/json"
-    API_VERSION = "2.251"
+    API_VERSION = Configuration::DEFAULT_API_VERSION
+    UNAUTHORIZED = 401
 
     attr_reader :config, :username, :password
     attr_accessor :session_cookie
 
-    def initialize(username:, password:, config: nil)
+    # Does not connect: the client logs in on the first call, or when you call login!.
+    # Without username, it uses config.username and config.password. With a
+    # username, it never uses the password from the configuration.
+    # Give a session_cookie from an earlier login to skip the login request.
+    # Without a password, an expired session raises AuthenticationError.
+    def initialize(username: nil, password: nil, config: nil, session_cookie: nil)
       @config = config || Fripa.config
-      @username = username
-      @password = password
-      @session_cookie = authenticator.login!
+      @username = username || @config.username
+      @password = username ? password : password || @config.password
+      @session_cookie = session_cookie unless session_cookie.to_s.empty?
+      @logged_in = !@session_cookie.nil?
+      authenticator.validate_credentials! unless @logged_in
     end
 
     def users
@@ -34,56 +42,105 @@ module Fripa
       @authenticator ||= Authenticator.new(self)
     end
 
+    # Logs in now and returns the session cookie. Raises AuthenticationError
+    # if the credentials are wrong.
+    def login!
+      self.session_cookie = authenticator.login!
+      @logged_in = true
+      session_cookie
+    end
+
+    def logged_in?
+      @logged_in
+    end
+
     def call(method, args = [], options = {})
+      login! unless logged_in?
       response = perform_request(method, args, options)
+      response = reauthenticate_and_retry(method, args, options) if response.status == UNAUTHORIZED
 
       raise ConnectionError, "API call failed: #{response.status}" unless response.success?
 
       parse_response(response)
     end
 
+    # Sends several commands in one HTTP request. Each command is
+    # [method, args = [], options = {}]. Per-command errors are not raised:
+    # check result["result"]["results"][i]["error"].
+    def batch(*commands)
+      requests = commands.map do |method, args = [], options = {}|
+        { method: method, params: [args, options.merge(version: config.api_version)] }
+      end
+      call("batch", requests)
+    end
+
+    # Shared by Authenticator, so login and API calls reuse one connection.
+    def connection
+      @connection ||= Faraday.new(url: config.base_url.to_s, request: request_options) do |f|
+        f.adapter(*Array(config.adapter || Faraday.default_adapter))
+        f.ssl.verify = config.verify_ssl
+      end
+    end
+
+    def referer
+      @referer ||= "#{config.base_url}/ipa"
+    end
+
+    def inspect
+      "#<#{self.class.name} username=#{username.inspect} host=#{config.host.inspect}>"
+    end
+
     private
 
+    def reauthenticate_and_retry(method, args, options)
+      raise AuthenticationError, "Session expired and no password to log in again" if password.to_s.empty?
+
+      login!
+      perform_request(method, args, options)
+    end
+
     def perform_request(method, args, options)
       connection.post(API_PATH) do |request|
         request.headers["Content-Type"] = "application/json"
-        request.headers["Referer"] = "#{config.base_url}/ipa"
+        request.headers["Referer"] = referer
         request.headers["Cookie"] = session_cookie
         request.body = build_request_body(method, args, options).to_json
       end
+    rescue Faraday::Error => e
+      raise ConnectionError, "API call failed: #{e.message}"
     end
 
     def build_request_body(method, args, options)
       {
         method: method,
-        params: [args, options.merge(version: API_VERSION)],
+        params: [args, options.merge(version: config.api_version)],
         id: 0
       }
     end
 
     def parse_response(response)
       parsed = JSON.parse(response.body)
+      raise ConnectionError, "API call failed: unexpected response" unless parsed.is_a?(Hash)
+
       raise_if_error(parsed)
       parsed
+    rescue JSON::ParserError
+      raise ConnectionError, "API call failed: invalid JSON response"
     end
 
     def raise_if_error(parsed)
-      return unless parsed["error"]
+      if (error = parsed["error"])
+        raise ResponseError.new(code: error["code"], message: error["message"] || error["name"], data: error["data"])
+      end
+
+      return unless config.raise_on_partial_failure
 
-      error = parsed["error"]
-      raise ResponseError.new(
-        code: error["code"],
-        message: error["message"] || error["name"],
-        data: error["data"]
-      )
+      failed = parsed.dig("result", "failed")
+      raise PartialFailureError, failed if PartialFailureError.failures(failed).any?
     end
 
-    def connection
-      @connection ||= Faraday.new(url: config.base_url.to_s) do |f|
-        f.request :url_encoded
-        f.adapter Faraday.default_adapter
-        f.ssl.verify = config.verify_ssl
-      end
+    def request_options
+      { timeout: config.timeout, open_timeout: config.open_timeout }.compact
     end
   end
 end

data/lib/fripa/configuration.rb

@@ -6,13 +6,39 @@ require "uri"
 module Fripa
   # Configuration for Fripa
   class Configuration
-    attr_accessor :host, :port, :scheme, :verify_ssl
+    DEFAULT_API_VERSION = "2.251"
+    SCHEMES = %w[http https].freeze
 
-    def initialize(host: nil, port: nil, scheme: "https", verify_ssl: true)
+    attr_accessor :host, :port, :scheme, :verify_ssl, :api_version, :timeout, :open_timeout, :adapter,
+                  :raise_on_partial_failure, :username, :password
+
+    # username and password are only used by Fripa.client and by
+    # Fripa::Client.new without a username.
+    def initialize(host: nil, port: nil, scheme: "https", verify_ssl: true, api_version: DEFAULT_API_VERSION,
+                   timeout: nil, open_timeout: nil, adapter: nil, raise_on_partial_failure: false,
+                   username: nil, password: nil)
       @host = host
       @port = port
       @scheme = scheme
       @verify_ssl = verify_ssl
+      @api_version = api_version
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @adapter = adapter
+      @raise_on_partial_failure = raise_on_partial_failure
+      @username = username
+      @password = password
+    end
+
+    # Values that change how a client connects or logs in. Fripa.client builds
+    # a new client when they change.
+    def options
+      { host:, port:, scheme:, verify_ssl:, api_version:, timeout:, open_timeout:, adapter:,
+        raise_on_partial_failure:, username:, password: }
+    end
+
+    def inspect
+      "#<#{self.class.name} host=#{host.inspect} scheme=#{scheme.inspect} username=#{username.inspect}>"
     end
 
     def base_url
@@ -30,18 +56,41 @@ module Fripa
     private
 
     def build_uri(path: nil)
-      raise ArgumentError, "host is required" if host.nil? || host.empty?
+      raise ArgumentError, "host is required" if host.to_s.empty?
+
+      normalized_scheme = scheme.to_s.downcase
+      raise ArgumentError, "scheme must be one of: #{SCHEMES.join(", ")}" unless SCHEMES.include?(normalized_scheme)
 
-      uri_class = scheme == "https" ? URI::HTTPS : URI::HTTP
+      uri_class = normalized_scheme == "https" ? URI::HTTPS : URI::HTTP
       uri_class.build(host: host, port: port, path: path)
     end
   end
 
+  @client_lock = Mutex.new
+
   class << self
     def config
       @config ||= Configuration.new
     end
 
+    # A client for the account in Fripa.config (username and password), shared
+    # by the whole process. It is built on first use, and again when the
+    # configuration changes. Use Fripa::Client.new for other accounts.
+    def client
+      @client_lock.synchronize do
+        unless @client&.config.equal?(config) && @client_options == config.options
+          @client = Client.new(config: config)
+          @client_options = config.options
+        end
+        @client
+      end
+    end
+
+    # Forgets the shared client (e.g. between tests). The next Fripa.client builds a new one.
+    def reset_client!
+      @client_lock.synchronize { @client = @client_options = nil }
+    end
+
     def config=(value)
       @config = case value
                 when Hash

data/lib/fripa/errors.rb

@@ -14,4 +14,27 @@ module Fripa
       super(message)
     end
   end
+
+  # Raised when FreeIPA answers without an error but reports per-entry failures,
+  # e.g. group_add_member with a user that does not exist or is already a member.
+  # Only raised with config.raise_on_partial_failure = true.
+  # #data holds the full "failed" hash from the response.
+  class PartialFailureError < ResponseError
+    def initialize(failed)
+      super(code: nil, message: self.class.first_reason(failed), data: failed)
+    end
+
+    def self.failures(failed)
+      return [] unless failed.is_a?(Hash)
+
+      failed.values.flat_map do |types|
+        types.is_a?(Hash) ? types.values.flat_map { |entries| Array(entries) } : Array(types)
+      end
+    end
+
+    def self.first_reason(failed)
+      entry = failures(failed).first
+      entry.is_a?(Array) ? entry.last.to_s : entry.to_s
+    end
+  end
 end

data/lib/fripa/resources/user.rb

@@ -32,11 +32,13 @@ module Fripa
         call("user_del", [uid])
       end
 
-      def passwd(uid, new_password, current_password, **options)
+      # current_password is only needed when users change their own password.
+      # Admins can omit it to reset the password of another user.
+      def passwd(uid, new_password, current_password = nil, **options)
         validate_identifier!(uid, "uid")
         validate_password!(new_password, "new_password")
-        validate_password!(current_password, "current_password")
-        call("passwd", [uid, new_password, current_password], options)
+        validate_password!(current_password, "current_password") unless current_password.nil?
+        call("passwd", [uid, new_password, current_password].compact, options)
       end
 
       private

data/lib/fripa/resources/vault.rb

@@ -5,6 +5,28 @@ require "base64"
 module Fripa
   module Resources
     class Vault < Base
+      NOT_FOUND = 4001
+
+      # The KRA transport certificate belongs to the server, not to an account,
+      # and it is public. So all clients of one process share it, per server URL:
+      # a service account and per-user clients fetch it only once.
+      @transport_certs = {}
+      @transport_certs_lock = Mutex.new
+
+      class << self
+        def transport_cert(key)
+          @transport_certs_lock.synchronize { @transport_certs[key] ||= yield }
+        end
+
+        def forget_transport_cert(key)
+          @transport_certs_lock.synchronize { @transport_certs.delete(key) }
+        end
+
+        def clear_transport_certs!
+          @transport_certs_lock.synchronize { @transport_certs.clear }
+        end
+      end
+
       def show(cn, **scope)
         validate_identifier!(cn, "cn")
         call("vault_show", [cn], scope)
@@ -15,24 +37,32 @@ module Fripa
         call("vault_add_internal", [cn], { ipavaulttype: "standard" }.merge(scope))
       end
 
-      def archive(cn, data:, **scope)
+      # ipa_format: true stores the data like `ipa vault-archive`, so the ipa CLI can read it.
+      # The default (false) stores the raw bytes, as in previous versions.
+      def archive(cn, data:, ipa_format: false, **scope)
         validate_identifier!(cn, "cn")
-        transport_cert_der = fetch_transport_cert
+        data = VaultTransport.to_ipa_format(data) if ipa_format
         payload = VaultTransport.wrap(data, transport_cert_der)
-        call("vault_archive_internal", [cn], binary_encode(payload).merge(wrapping_algo: VaultTransport::WRAPPING_ALGO).merge(scope))
+        with_transport_cert_refresh do
+          call("vault_archive_internal", [cn],
+               binary_encode(payload).merge(wrapping_algo: VaultTransport::WRAPPING_ALGO).merge(scope))
+        end
       end
 
-      def retrieve(cn, **scope)
+      # ipa_format: true reads data stored by `ipa vault-archive` (or archive with ipa_format: true).
+      # Returns nil if the vault has no data.
+      def retrieve(cn, ipa_format: false, **scope)
         validate_identifier!(cn, "cn")
         session_key = VaultTransport.generate_session_key
-        response = call_retrieve(cn, session_key, **scope)
-        result = response.dig("result", "result")
+        result = call_retrieve(cn, session_key, **scope).dig("result", "result")
+        return nil unless result&.key?("vault_data")
 
-        VaultTransport.decrypt(
+        data = VaultTransport.decrypt(
           vault_data: extract_value(result["vault_data"]),
           nonce: extract_value(result["nonce"]),
           session_key: session_key
         )
+        ipa_format ? VaultTransport.from_ipa_format(data) : data
       end
 
       def add_member(cn, **scope)
@@ -47,20 +77,33 @@ module Fripa
 
       private
 
+      def transport_cert_der
+        self.class.transport_cert(client.config.base_url.to_s) { fetch_transport_cert }
+      end
+
+      # If the server rejects a payload, its certificate can have changed
+      # (e.g. renewed). Forget it, so that the next call fetches it again.
+      def with_transport_cert_refresh
+        yield
+      rescue ResponseError => e
+        self.class.forget_transport_cert(client.config.base_url.to_s) unless e.code == NOT_FOUND
+        raise
+      end
+
       def fetch_transport_cert
         response = call("vaultconfig_show", [], { all: true })
-        cert = response["result"]["result"]["transport_cert"]
-        Base64.decode64(cert.is_a?(Hash) ? cert["__base64__"] : cert)
+        Base64.decode64(extract_value(response.dig("result", "result", "transport_cert")))
       end
 
       def call_retrieve(cn, session_key, **scope)
-        cert = OpenSSL::X509::Certificate.new(fetch_transport_cert)
-        encrypted_key = cert.public_key.public_encrypt(session_key, VaultTransport::RSA_PADDING)
+        encrypted_key = VaultTransport.encrypt_session_key(session_key, transport_cert_der)
 
-        call("vault_retrieve_internal", [cn], {
-          session_key: { "__base64__" => Base64.strict_encode64(encrypted_key) },
-          wrapping_algo: VaultTransport::WRAPPING_ALGO
-        }.merge(scope))
+        with_transport_cert_refresh do
+          call("vault_retrieve_internal", [cn], {
+            session_key: { "__base64__" => Base64.strict_encode64(encrypted_key) },
+            wrapping_algo: VaultTransport::WRAPPING_ALGO
+          }.merge(scope))
+        end
       end
 
       def binary_encode(hash)

data/lib/fripa/vault_transport.rb

@@ -2,6 +2,7 @@
 
 require "openssl"
 require "base64"
+require "json"
 
 module Fripa
   module VaultTransport
@@ -51,12 +52,17 @@ module Fripa
 
     def self.unwrap(vault_data:, session_key:, nonce:, private_key:)
       decrypted_session_key = private_key.private_decrypt(Base64.decode64(session_key), RSA_PADDING)
+      decrypt(vault_data: vault_data, nonce: nonce, session_key: decrypted_session_key)
+    end
 
-      decipher = OpenSSL::Cipher.new(CIPHER)
-      decipher.decrypt
-      decipher.key = decrypted_session_key
-      decipher.iv = Base64.decode64(nonce)
-      decipher.update(Base64.decode64(vault_data)) + decipher.final
+    # The ipa CLI (ipa vault-archive / vault-retrieve) stores {"data": base64(data)},
+    # not the raw bytes. Use these to read or write vaults shared with the CLI.
+    def self.to_ipa_format(data)
+      JSON.generate("data" => Base64.strict_encode64(data))
+    end
+
+    def self.from_ipa_format(json)
+      Base64.strict_decode64(JSON.parse(json).fetch("data"))
     end
 
     def self.generate_transport_key

data/lib/fripa/version.rb

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

data/sig/fripa.rbs

@@ -1,4 +1,162 @@
 module Fripa
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  type json_hash = Hash[String, untyped]
+
+  def self.config: () -> Configuration
+  def self.config=: (Configuration | Hash[Symbol, untyped] value) -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.client: () -> Client
+  def self.reset_client!: () -> void
+
+  class Configuration
+    DEFAULT_API_VERSION: String
+    SCHEMES: Array[String]
+
+    attr_accessor host: String?
+    attr_accessor port: Integer?
+    attr_accessor scheme: String
+    attr_accessor verify_ssl: bool
+    attr_accessor api_version: String
+    attr_accessor timeout: Numeric?
+    attr_accessor open_timeout: Numeric?
+    attr_accessor adapter: untyped
+    attr_accessor raise_on_partial_failure: bool
+    attr_accessor username: String?
+    attr_accessor password: String?
+
+    def initialize: (?host: String?, ?port: Integer?, ?scheme: String, ?verify_ssl: bool, ?api_version: String,
+                     ?timeout: Numeric?, ?open_timeout: Numeric?, ?adapter: untyped,
+                     ?raise_on_partial_failure: bool, ?username: String?, ?password: String?) -> void
+    def options: () -> Hash[Symbol, untyped]
+    def base_url: () -> URI::Generic
+    def login_url: () -> URI::Generic
+    def api_url: () -> URI::Generic
+
+    private
+
+    def build_uri: (?path: String?) -> URI::Generic
+  end
+
+  class Error < StandardError
+  end
+
+  class AuthenticationError < Error
+  end
+
+  class ConnectionError < Error
+  end
+
+  class ResponseError < Error
+    attr_reader code: Integer?
+    attr_reader data: untyped
+
+    def initialize: (code: Integer?, message: String?, ?data: untyped) -> void
+  end
+
+  class PartialFailureError < ResponseError
+    def initialize: (json_hash failed) -> void
+    def self.failures: (untyped failed) -> Array[untyped]
+    def self.first_reason: (untyped failed) -> String
+  end
+
+  class Client
+    API_PATH: String
+    API_VERSION: String
+    UNAUTHORIZED: Integer
+
+    attr_reader config: Configuration
+    attr_reader username: String?
+    attr_reader password: String?
+    attr_accessor session_cookie: String?
+
+    def initialize: (?username: String?, ?password: String?, ?config: Configuration?, ?session_cookie: String?) -> void
+    def login!: () -> String?
+    def logged_in?: () -> bool
+    def users: () -> Resources::User
+    def groups: () -> Resources::Group
+    def vault: () -> Resources::Vault
+    def authenticator: () -> Authenticator
+    def call: (String method, ?Array[untyped] args, ?Hash[Symbol, untyped] options) -> json_hash
+    def batch: (*Array[untyped] commands) -> json_hash
+    def connection: () -> untyped
+    def referer: () -> String
+  end
+
+  class Authenticator
+    LOGIN_PATH: String
+    CONTENT_TYPE: String
+    COOKIE_SEPARATOR: Regexp
+
+    attr_reader client: Client
+
+    def initialize: (Client client) -> void
+    def login!: () -> String?
+    def validate_credentials!: () -> void
+  end
+
+  module VaultTransport
+    CIPHER: String
+    WRAPPING_ALGO: String
+    KEY_SIZE: Integer
+    IV_SIZE: Integer
+    RSA_KEY_SIZE: Integer
+    RSA_PADDING: Integer
+
+    def self.generate_session_key: () -> String
+    def self.decrypt: (vault_data: String, nonce: String, session_key: String) -> String
+    def self.wrap: (String data, String transport_cert_der) -> { vault_data: String, session_key: String, nonce: String }
+    def self.encrypt_data: (String data, String key, String nonce) -> String
+    def self.encrypt_session_key: (String session_key, String cert_der) -> String
+    def self.unwrap: (vault_data: String, session_key: String, nonce: String, private_key: OpenSSL::PKey::RSA) -> String
+    def self.to_ipa_format: (String data) -> String
+    def self.from_ipa_format: (String json) -> String
+    def self.generate_transport_key: () -> OpenSSL::PKey::RSA
+  end
+
+  module Resources
+    class Base
+      attr_reader client: Client
+
+      def initialize: (Client client) -> void
+    end
+
+    class User < Base
+      REQUIRED_ADD_FIELDS: Array[Symbol]
+
+      def find: (?String? uid, **untyped options) -> json_hash
+      def show: (String uid) -> json_hash
+      def add: (String uid, **untyped attributes) -> json_hash
+      def mod: (String uid, **untyped attributes) -> json_hash
+      def delete: (String uid) -> json_hash
+      def passwd: (String uid, String new_password, ?String? current_password, **untyped options) -> json_hash
+    end
+
+    class Group < Base
+      def find: (?String? cn, **untyped options) -> json_hash
+      def show: (String cn) -> json_hash
+      def add: (String cn, **untyped attributes) -> json_hash
+      def mod: (String cn, **untyped attributes) -> json_hash
+      def delete: (String cn) -> json_hash
+      def add_member: (String cn, **untyped members) -> json_hash
+      def remove_member: (String cn, **untyped members) -> json_hash
+      def add_member_manager: (String cn, **untyped managers) -> json_hash
+      def remove_member_manager: (String cn, **untyped managers) -> json_hash
+    end
+
+    class Vault < Base
+      NOT_FOUND: Integer
+
+      def self.transport_cert: (String key) { () -> String } -> String
+      def self.forget_transport_cert: (String key) -> String?
+      def self.clear_transport_certs!: () -> void
+
+      def show: (String cn, **untyped scope) -> json_hash
+      def add: (String cn, **untyped scope) -> json_hash
+      def archive: (String cn, data: String, ?ipa_format: bool, **untyped scope) -> json_hash
+      def retrieve: (String cn, ?ipa_format: bool, **untyped scope) -> String?
+      def add_member: (String cn, **untyped scope) -> json_hash
+      def delete: (String cn, **untyped scope) -> json_hash
+    end
+  end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: fripa
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Bruno Costanzo
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -13,16 +13,16 @@ dependencies:
   name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -37,21 +37,17 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: A Ruby client library for interacting with FreeIPA's JSON-RPC API
+description: 'A Ruby client library for FreeIPA''s JSON-RPC API: users, groups, vaults
+  and batch calls.'
 email:
 - dev.bcostanzo@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".env.example"
-- ".simplecov"
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- CONTRIBUTING.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/fripa.rb
 - lib/fripa/authenticator.rb
 - lib/fripa/client.rb
@@ -68,9 +64,11 @@ homepage: https://github.com/renuo/fripa
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/renuo/fripa
   source_code_uri: https://github.com/renuo/fripa
   changelog_uri: https://github.com/renuo/fripa/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/renuo/fripa/issues
+  documentation_uri: https://rubydoc.info/gems/fripa
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -85,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby client for FreeIPA JSON-RPC API
 test_files: []

data/.env.example

@@ -1,4 +0,0 @@
-FREEIPA_HOST=ipa.example.com
-FREEIPA_USER=admin
-FREEIPA_PASSWORD=your-password
-FREEIPA_VERIFY_SSL=true

data/.simplecov

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-SimpleCov.start do
-  add_filter "/test/"
-  enable_coverage :branch
-  primary_coverage :branch
-end

data/CODE_OF_CONDUCT.md

@@ -1,132 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -1,96 +0,0 @@
-# Contributing to Fripa
-
-Thank you for your interest in contributing to Fripa! This document provides guidelines and instructions for contributing.
-
-## How to Contribute
-
-### Reporting Bugs
-
-If you find a bug, please open an issue on GitHub with:
-- A clear, descriptive title
-- Steps to reproduce the issue
-- Expected behavior vs. actual behavior
-- Your Ruby version and FreeIPA version
-- Any relevant code samples or error messages
-
-### Suggesting Features
-
-Feature suggestions are welcome! Please open an issue with:
-- A clear description of the feature
-- Use cases explaining why this feature would be useful
-- Any implementation ideas you might have
-
-### Pull Requests
-
-1. **Fork the repository** and create your branch from `main`
-2. **Make your changes** following our coding standards
-3. **Add tests** for any new functionality
-4. **Ensure all tests pass** by running `bin/test`
-5. **Run the linter** with `bundle exec rubocop`
-6. **Update documentation** if you're changing functionality
-7. **Submit your pull request** with a clear description of changes
-
-## Development Setup
-
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/brunocostanzo/fripa.git
-   cd fripa
-   ```
-
-2. Install dependencies:
-   ```bash
-   bin/setup
-   ```
-
-3. Run tests:
-   ```bash
-   bin/test
-   ```
-
-4. Run linter:
-   ```bash
-   bundle exec rubocop
-   ```
-
-## Coding Standards
-
-- Follow the [Ruby Style Guide](https://rubystyle.guide/)
-- Use RuboCop to check your code style
-- Write clear, self-documenting code
-- Add comments for complex logic
-- Keep methods small and focused
-- Maintain test coverage above 95%
-
-## Testing Guidelines
-
-- Write tests for all new features
-- Update tests when modifying existing features
-- Use VCR cassettes for API interactions
-- Ensure both line and branch coverage remain high
-- Test both success and error cases
-
-## Commit Messages
-
-Write clear, descriptive commit messages:
-- Use present tense ("Add feature" not "Added feature")
-- Capitalize the first letter
-- Keep the first line under 72 characters
-- Add detailed description if needed
-
-Example:
-```
-Add support for host management
-
-- Implement host resource with CRUD operations
-- Add tests with VCR cassettes
-- Update README with usage examples
-```
-
-## Questions?
-
-If you have questions about contributing, feel free to open an issue labeled "question".
-
-## Code of Conduct
-
-By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require "dotenv"
-Dotenv.load
-
-require "bundler/gem_tasks"
-require "minitest/test_task"
-
-Minitest::TestTask.create do |t|
-  t.warning = false
-end
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[test rubocop]