fripa 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d954bb6883076c8fbae4d9ef3f56d89fe96e38b2f01c4397f9d2d2a401aa855e
-  data.tar.gz: 11e1981ba74865e16c8f38fb1c345f3bbf43497d66627952dfbe465d22e198f8
+  metadata.gz: 5034dad8f9b68de329b79f4a447167c68f60edbf9310854f587a14b780f1c3f7
+  data.tar.gz: 9dc1b84130c58a48f67aeaa103c39893235c28123b38214acde4eefd40509762
 SHA512:
-  metadata.gz: 137b34f03e9f99bb1449acc51cef20f351bd5060e813efdac9ac71ff0d569d23aca4a538af358f08e74fc352576ebd4d07343be96bbd74ad6a5bbd918d210948
-  data.tar.gz: a01de4bc70e5ee242f28c1ed149917744a3d5d0acfe94b3ddcce08516db35b2c467d2a0f16bf0713455666db5bc3276b37a1e2db097d27fee613cb43f6e4e179
+  metadata.gz: 81e82e52a5d09927d3a69ecf550db4482a282faa7fee27b41fcea21d45d27c6764bd7aa45550a21f584ba11c6887b9a3e63829d7c199ca541be1757a7423352a
+  data.tar.gz: d95654a1a20db0c69f64ba9f007dd3074011b3eb685b561bf2c2cc6d1ebe1fd8056d0e655073bf4ed2de4e772193238081238049a9f7fc77c5439a74293c6dfa

data/CHANGELOG.md

@@ -1,5 +1,43 @@
+# 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.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 +58,10 @@ 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.2.0...HEAD
+[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:
@@ -143,6 +166,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 +207,43 @@ 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 client fetches the KRA transport certificate once and keeps it.
+
+#### 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 +256,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,7 +23,11 @@ module Fripa
 
       raise AuthenticationError, "Login failed: #{response.status}" unless response.success?
 
-      response.headers["set-cookie"]
+      session_cookie(response.headers["set-cookie"])
+    end
+
+    def inspect
+      "#<#{self.class.name} username=#{client.username.inspect}>"
     end
 
     private
@@ -31,19 +38,26 @@ module Fripa
     end
 
     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,7 +6,8 @@ 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
@@ -26,60 +27,98 @@ module Fripa
       @groups ||= Resources::Group.new(self)
     end
 
+    def vault
+      @vault ||= Resources::Vault.new(self)
+    end
+
     def authenticator
       @authenticator ||= Authenticator.new(self)
     end
 
     def call(method, args = [], options = {})
       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)
+      self.session_cookie = authenticator.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,23 @@ 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
+
+    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)
       @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
     end
 
     def base_url
@@ -30,9 +40,12 @@ 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

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Fripa
+  module Resources
+    class Vault < Base
+      def show(cn, **scope)
+        validate_identifier!(cn, "cn")
+        call("vault_show", [cn], scope)
+      end
+
+      def add(cn, **scope)
+        validate_identifier!(cn, "cn")
+        call("vault_add_internal", [cn], { ipavaulttype: "standard" }.merge(scope))
+      end
+
+      # 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")
+        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))
+      end
+
+      # 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
+        result = call_retrieve(cn, session_key, **scope).dig("result", "result")
+        return nil unless result&.key?("vault_data")
+
+        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)
+        validate_identifier!(cn, "cn")
+        call("vault_add_member", [cn], scope)
+      end
+
+      def delete(cn, **scope)
+        validate_identifier!(cn, "cn")
+        call("vault_del", [cn], scope)
+      end
+
+      private
+
+      # The KRA transport certificate does not change between calls, so we
+      # fetch it once per client (the ipa CLI caches it too).
+      def transport_cert_der
+        @transport_cert_der ||= fetch_transport_cert
+      end
+
+      def fetch_transport_cert
+        response = call("vaultconfig_show", [], { all: true })
+        Base64.decode64(extract_value(response.dig("result", "result", "transport_cert")))
+      end
+
+      def call_retrieve(cn, session_key, **scope)
+        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))
+      end
+
+      def binary_encode(hash)
+        hash.transform_values { |v| { "__base64__" => v } }
+      end
+
+      def extract_value(value)
+        value.is_a?(Hash) ? value["__base64__"] : value
+      end
+    end
+  end
+end

data/lib/fripa/vault_transport.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+
+module Fripa
+  module VaultTransport
+    CIPHER = "AES-128-CBC"
+    WRAPPING_ALGO = "aes-128-cbc"
+    KEY_SIZE = 16
+    IV_SIZE = 16
+    RSA_KEY_SIZE = 2048
+    RSA_PADDING = OpenSSL::PKey::RSA::PKCS1_PADDING
+
+    def self.generate_session_key
+      OpenSSL::Random.random_bytes(KEY_SIZE)
+    end
+
+    def self.decrypt(vault_data:, nonce:, session_key:)
+      decipher = OpenSSL::Cipher.new(CIPHER)
+      decipher.decrypt
+      decipher.key = session_key
+      decipher.iv = Base64.decode64(nonce)
+      decipher.update(Base64.decode64(vault_data)) + decipher.final
+    end
+
+    def self.wrap(data, transport_cert_der)
+      session_key = generate_session_key
+      nonce = OpenSSL::Random.random_bytes(IV_SIZE)
+      vault_data = encrypt_data(data, session_key, nonce)
+      encrypted_session_key = encrypt_session_key(session_key, transport_cert_der)
+
+      {
+        vault_data: Base64.strict_encode64(vault_data),
+        session_key: Base64.strict_encode64(encrypted_session_key),
+        nonce: Base64.strict_encode64(nonce)
+      }
+    end
+
+    def self.encrypt_data(data, key, nonce)
+      cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+      cipher.key = key
+      cipher.iv = nonce
+      cipher.update(data.b) + cipher.final
+    end
+
+    def self.encrypt_session_key(session_key, cert_der)
+      cert = OpenSSL::X509::Certificate.new(cert_der)
+      cert.public_key.public_encrypt(session_key, RSA_PADDING)
+    end
+
+    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
+
+    # 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
+      OpenSSL::PKey::RSA.generate(RSA_KEY_SIZE)
+    end
+  end
+end

data/lib/fripa/version.rb

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

data/lib/fripa.rb

@@ -7,6 +7,8 @@ require_relative "fripa/authenticator"
 require_relative "fripa/resources/base"
 require_relative "fripa/resources/user"
 require_relative "fripa/resources/group"
+require_relative "fripa/vault_transport"
+require_relative "fripa/resources/vault"
 require_relative "fripa/client"
 
 module Fripa

data/sig/fripa.rbs

@@ -1,4 +1,148 @@
 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
+
+  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
+
+    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) -> void
+    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?) -> void
+    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?
+  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
+      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,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: fripa
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Bruno Costanzo
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -23,20 +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:
-- ".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
@@ -45,15 +56,19 @@ files:
 - lib/fripa/resources/base.rb
 - lib/fripa/resources/group.rb
 - lib/fripa/resources/user.rb
+- lib/fripa/resources/vault.rb
+- lib/fripa/vault_transport.rb
 - lib/fripa/version.rb
 - sig/fripa.rbs
 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
@@ -68,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby client for FreeIPA JSON-RPC API
 test_files: []

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,14 +0,0 @@
-# frozen_string_literal: true
-
-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]