fripa 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5034dad8f9b68de329b79f4a447167c68f60edbf9310854f587a14b780f1c3f7
-  data.tar.gz: 9dc1b84130c58a48f67aeaa103c39893235c28123b38214acde4eefd40509762
+  metadata.gz: 2ac5a037cb023bb2f087a6d3f6482c4ca8fa8a1e7f7b70d7a01d88e8e7e62db8
+  data.tar.gz: a7f6e6894ee51a0195f4555e482e29752188805c0c908791232bc8fa7db272f0
 SHA512:
-  metadata.gz: 81e82e52a5d09927d3a69ecf550db4482a282faa7fee27b41fcea21d45d27c6764bd7aa45550a21f584ba11c6887b9a3e63829d7c199ca541be1757a7423352a
-  data.tar.gz: d95654a1a20db0c69f64ba9f007dd3074011b3eb685b561bf2c2cc6d1ebe1fd8056d0e655073bf4ed2de4e772193238081238049a9f7fc77c5439a74293c6dfa
+  metadata.gz: be1d590702cd1e50e0995b6e8b65683c691ec0f03522ff755126645566d7f87cbd7be9c311db970900ee6b28a3931a5563cadd7cae1c9d24d3982b6bea94c3c5
+  data.tar.gz: 9acd2a8785b03cabf3a4902db60efdc6e5c895137759c8371ecf7577ce94f8c37daab75631ed81ea4918cfe795ebf74e23af716fcf3bfbfa3fdde4bd2b3e19d3

data/CHANGELOG.md

@@ -6,6 +6,19 @@ 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
@@ -59,7 +72,8 @@ Initial release of Fripa - A Ruby client for the FreeIPA JSON-RPC API.
 - Full test suite with VCR cassettes
 - Complete API documentation and usage examples
 
-[Unreleased]: https://github.com/renuo/fripa/compare/v0.2.0...HEAD
+[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

data/README.md

@@ -114,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)
@@ -228,7 +256,9 @@ 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.
+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
 

data/lib/fripa/authenticator.rb

@@ -30,13 +30,13 @@ module Fripa
       "#<#{self.class.name} username=#{client.username.inspect}>"
     end
 
-    private
-
     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
       client.connection.post(LOGIN_PATH) do |request|
         request.headers["Content-Type"] = CONTENT_TYPE

data/lib/fripa/client.rb

@@ -12,11 +12,18 @@ module Fripa
     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
@@ -35,7 +42,20 @@ 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
 
@@ -73,7 +93,9 @@ module Fripa
     private
 
     def reauthenticate_and_retry(method, args, options)
-      self.session_cookie = authenticator.login!
+      raise AuthenticationError, "Session expired and no password to log in again" if password.to_s.empty?
+
+      login!
       perform_request(method, args, options)
     end
 

data/lib/fripa/configuration.rb

@@ -10,10 +10,13 @@ module Fripa
     SCHEMES = %w[http https].freeze
 
     attr_accessor :host, :port, :scheme, :verify_ssl, :api_version, :timeout, :open_timeout, :adapter,
-                  :raise_on_partial_failure
+                  :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)
+                   timeout: nil, open_timeout: nil, adapter: nil, raise_on_partial_failure: false,
+                   username: nil, password: nil)
       @host = host
       @port = port
       @scheme = scheme
@@ -23,6 +26,19 @@ module Fripa
       @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
@@ -50,11 +66,31 @@ module Fripa
     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/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)
@@ -21,8 +43,10 @@ module Fripa
         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))
+        with_transport_cert_refresh do
+          call("vault_archive_internal", [cn],
+               binary_encode(payload).merge(wrapping_algo: VaultTransport::WRAPPING_ALGO).merge(scope))
+        end
       end
 
       # ipa_format: true reads data stored by `ipa vault-archive` (or archive with ipa_format: true).
@@ -53,10 +77,17 @@ module Fripa
 
       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
+        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
@@ -67,10 +98,12 @@ module Fripa
       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))
+        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/version.rb

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

data/sig/fripa.rbs

@@ -6,6 +6,8 @@ module Fripa
   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
@@ -20,10 +22,13 @@ module Fripa
     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) -> void
+                     ?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
@@ -61,11 +66,13 @@ module Fripa
     UNAUTHORIZED: Integer
 
     attr_reader config: Configuration
-    attr_reader username: String
-    attr_reader password: String
+    attr_reader username: String?
+    attr_reader password: String?
     attr_accessor session_cookie: String?
 
-    def initialize: (username: String, password: String, ?config: Configuration?) -> void
+    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
@@ -85,6 +92,7 @@ module Fripa
 
     def initialize: (Client client) -> void
     def login!: () -> String?
+    def validate_credentials!: () -> void
   end
 
   module VaultTransport
@@ -137,6 +145,12 @@ module Fripa
     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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fripa
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Bruno Costanzo