k9o 1.3.0 → 1.5.0

data/lib/k9o/kibo_client_core.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+require 'timeout'
+require_relative 'kerror'
+require_relative 'crypto'
+
+module K9o
+  # The client core for +client.crypto+ on a BYOK or HYOK project: it opens and seals data on this machine, against your
+  # own KMS or HSM, so the platform never sees plaintext or the key. There is no crypto here. Sealing, opening, the key
+  # pin and the token exchange all run in the audited Rust core (+kibo-kms-rest-ffi+, zk-bundle-v2.16.3 or later). This
+  # class only sequences them:
+  #
+  #   federated token (platform) -> acquire_kms_credential (your cloud) -> app_crypto_seal / app_crypto_open (your KMS)
+  #
+  # Everything that picks a key, a provider, a role, a region or an endpoint comes from the configuration you pass here.
+  # Nothing comes from the platform's answer: the token response's +provider+ and +project_id+ are checked against your
+  # configuration, and a mismatch is refused, never followed.
+  #
+  #   core = K9o::KiboClientCore.new(
+  #     provider: :aws, posture: :byok,
+  #     key_ref: { version: 1, external_ref: key_arn },
+  #     provider_config: { aws_region: 'eu-central-1' },
+  #     federation: { provider: 'aws', role_arn: role_arn, session_name: 'app', region: 'eu-central-1',
+  #                   key_arn: key_arn, duration_secs: 900 },
+  #     expected_key_refs: [key_arn],                       # required
+  #     federated_token: client.crypto.method(:federated_token),
+  #     core: K9o::KiboFfiCore.new
+  #   )
+  #   client.crypto.use_client_core(core)
+  #
+  # +core:+ is the bound Kibo core: K9o::KiboFfiCore.new, which wraps the generated binding and the native library, or any
+  # object that responds to +app_crypto_seal_blocking+, +app_crypto_open_blocking+, +acquire_kms_credential_blocking+ and
+  # +core_capabilities+ (Ruby has no async, so it calls the +_blocking+ exports). Inputs are passed as Hashes with snake_case
+  # keys, the field names of the core's input types; an answer may be a Hash or an object with the same readers.
+  # Ciphertext is the base64 String of the container bytes.
+  class KiboClientCore
+    EXCHANGE_TIMEOUT = 'KIBO_EXCHANGE_TIMEOUT'
+    CORE_FUNCTIONS = %i[app_crypto_seal_blocking app_crypto_open_blocking acquire_kms_credential_blocking
+                        core_capabilities].freeze
+    PROVIDER_WIRE = { aws: 'aws-kms', gcp: 'gcp-kms', azure: 'azure-kv', vault: 'hashicorp-vault' }.freeze
+    POSTURES = %i[byok hyok].freeze
+    OPS = %w[encrypt decrypt rewrap].freeze
+    # Refresh a credential this long before it expires.
+    SKEW_SECS = 60
+    DEFAULT_DEADLINE_SECS = 30
+
+    Cred = Struct.new(:secret, :expires_at_unix_secs) do
+      def inspect
+        "#<struct K9o::KiboClientCore::Cred secret=[redacted] expires_at_unix_secs=#{expires_at_unix_secs.inspect}>"
+      end
+
+      def to_s
+        inspect
+      end
+
+      def to_h
+        { secret: secret, expires_at_unix_secs: expires_at_unix_secs }
+      end
+    end
+    private_constant :Cred
+
+    # +provider+: :aws, :gcp, :azure or :vault, the same as +federation[:provider]+.
+    # +posture+: :byok or :hyok.
+    # +project_id+: the project id (+proj_...+), bound into what is sealed. Leave it out only if you want the token
+    #   response's value; a value given here is never overridden.
+    # +key_ref+: the exact key this application uses, +{ version:, external_ref: }+.
+    # +provider_config+: +{ aws_region:, vault_address: }+ (only the ones you need).
+    # +federation+: how to exchange the platform's identity token for a credential on your cloud (the core's
+    #   FfiFederationSpec, with a String +provider+ of "aws", "gcp", "azure" or "vault"). For "vault" it is
+    #   +{ provider: 'vault', vault_addr:, jwt_auth_mount:, role: }+, where +jwt_auth_mount+ is the JWT auth mount: the name
+    #   Vault serves the JWT login under, "jwt" for +auth/jwt+ (not the transit mount, which comes from the key reference).
+    #   It is handed to the core as the core's own +mount+ field.
+    # +expected_key_refs+: the keys this application allows. Required and non-empty.
+    # +federated_token+: anything that answers +call(crypt, op)+ with a Crypto::FederatedToken, for example
+    #   +client.crypto.method(:federated_token)+.
+    # +exchange_deadline+: seconds the exchange may take before it is abandoned. Default 30.
+    # +now+: the host clock, a callable answering Unix seconds.
+    def initialize(provider:, posture:, key_ref:, federation:, expected_key_refs:, federated_token:, core:,
+                   project_id: nil, provider_config: {}, exchange_deadline: DEFAULT_DEADLINE_SECS,
+                   now: -> { Time.now.to_i })
+      @provider = provider.respond_to?(:to_sym) ? provider.to_sym : provider
+      @federation = symbolize(federation)
+      check_vault_federation(@federation) if @federation[:provider].to_s == 'vault'
+      fed_provider = @federation[:provider].respond_to?(:to_sym) ? @federation[:provider].to_sym : @federation[:provider]
+      raise bad('provider and federation.provider must be the same cloud', 'provider') unless @provider == fed_provider
+      raise bad('provider must be :aws, :gcp, :azure or :vault', 'provider') unless PROVIDER_WIRE.key?(@provider)
+
+      @posture = posture.respond_to?(:to_sym) ? posture.to_sym : posture
+      raise bad('posture must be :byok or :hyok', 'posture') unless POSTURES.include?(@posture)
+
+      @pin = check_pin(expected_key_refs)
+      key_ref = symbolize(key_ref)
+      @key_ref = { version: key_ref[:version], external_ref: key_ref[:external_ref] }
+      unless @key_ref[:external_ref].is_a?(String) && Crypto.key_ref_matches?(@key_ref[:external_ref], @pin, provider: @provider)
+        raise bad('key_ref is not in expected_key_refs', 'keyRef')
+      end
+
+      raise bad('federated_token must respond to call(crypt, op)', 'federatedToken') unless federated_token.respond_to?(:call)
+
+      @project_id = project_id
+      @provider_config = symbolize(provider_config)
+      @federated_token = federated_token
+      @core = core
+      @deadline = exchange_deadline
+      @now = now
+      @creds = {}
+      @mutex = Mutex.new
+      @caps_checked = false
+    end
+
+    # Declares that this core enforces the key pin (see Crypto#use_client_core).
+    def enforces_expected_key_refs?
+      true
+    end
+
+    # Neither the cached credentials nor the callables appear here.
+    def inspect
+      "#<#{self.class.name} provider=#{@provider.inspect} posture=#{@posture.inspect}>"
+    end
+
+    def to_s
+      inspect
+    end
+
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
+
+    # Seal each item's plaintext under the configured key. Items: +{ plaintext:, context: }+. Answers
+    # +{ 'items' => [{ 'ok' => true, 'ciphertext' => base64 } | { 'ok' => false, 'code', 'message' }] }+.
+    def encrypt(crypt, items, **options)
+      pin = effective_pin(options)
+      return refused(items.size) unless key_in_pin?(pin)
+
+      core = loaded_core
+      cred, project_id, secrets = credential(core, crypt, 'encrypt')
+      out = items.map do |it|
+        guard(secrets) do
+          { 'ok' => true, 'ciphertext' => seal(core, cred, project_id, crypt, it[:plaintext], it[:context], pin, options) }
+        end
+      end
+      { 'items' => out }
+    end
+
+    # Open each item's ciphertext. Answers +'plaintext'+ as a binary String (and +'text'+ when it is valid UTF-8).
+    def decrypt(crypt, items, **options)
+      pin = effective_pin(options)
+      return refused(items.size) unless key_in_pin?(pin)
+
+      core = loaded_core
+      cred, project_id, secrets = credential(core, crypt, 'decrypt')
+      out = items.map do |it|
+        guard(secrets) do
+          plain = open_item(core, cred, project_id, crypt, it[:ciphertext], it[:context], pin, options)
+          item = { 'ok' => true, 'plaintext' => plain }
+          text = plain.dup.force_encoding(Encoding::UTF_8)
+          item['text'] = text if text.valid_encoding?
+          item
+        end
+      end
+      { 'items' => out }
+    end
+
+    # Open each item, then seal it again under the configured key, with a "rewrap" federated token.
+    def rewrap(crypt, items, **options)
+      pin = effective_pin(options)
+      return refused(items.size) unless key_in_pin?(pin)
+
+      core = loaded_core
+      cred, project_id, secrets = credential(core, crypt, 'rewrap')
+      out = items.map do |it|
+        guard(secrets) do
+          plain = open_item(core, cred, project_id, crypt, it[:ciphertext], it[:context], pin, options)
+          { 'ok' => true, 'ciphertext' => seal(core, cred, project_id, crypt, plain, it[:context], pin, options) }
+        end
+      end
+      { 'items' => out }
+    end
+
+    private
+
+    def bad(message, field)
+      KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: message, context: { 'field' => field })
+    end
+
+    def symbolize(hash)
+      raise bad('expected a Hash', 'config') unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+
+    def check_vault_federation(fed)
+      %i[vault_addr jwt_auth_mount role].each do |field|
+        next if fed[field].is_a?(String) && !fed[field].strip.empty?
+
+        raise bad("federation.#{field} is required for vault and must be a non-empty String", "federation.#{field}")
+      end
+    end
+
+    # The spec as the core names its fields: the SDK's +jwt_auth_mount+ is the core's +mount+.
+    def core_spec
+      spec = @federation.dup
+      spec[:mount] = spec.delete(:jwt_auth_mount) if spec.key?(:jwt_auth_mount)
+      spec
+    end
+
+    def check_pin(refs)
+      pin = Crypto.check_expected_key_refs(refs)
+      if pin.nil?
+        raise bad('expected_key_refs is required: this client never seals or opens without a key pin', 'expectedKeyRefs')
+      end
+
+      pin
+    end
+
+    def effective_pin(options)
+      p = options[:expected_key_refs].nil? ? @pin : options[:expected_key_refs]
+      unless p.is_a?(Array) && !p.empty?
+        raise bad('expected_key_refs is empty: refusing to call without a key pin', 'expectedKeyRefs')
+      end
+
+      p
+    end
+
+    # The call's own pin is matched against the configured key before any token is fetched or any credential is exchanged;
+    # the key version is ignored.
+    def key_in_pin?(pin)
+      Crypto.key_ref_matches?(@key_ref[:external_ref], pin, provider: @provider)
+    end
+
+    def refused(count)
+      item = { 'ok' => false, 'code' => 'K9O_CRYPTO_UNEXPECTED_KEY',
+               'message' => "the configured key is not in this call's expected_key_refs; nothing was sent" }
+      { 'items' => Array.new(count) { item.dup } }
+    end
+
+    # The core, once it is known to be 2.16.3 or later and to declare that it enforces the pin. Nothing is fetched or sent
+    # before this passes.
+    def loaded_core
+      CORE_FUNCTIONS.each do |fn|
+        next if @core.respond_to?(fn)
+
+        raise KError.new(code: 'KIBO_WASM_ERROR',
+                         message: "the Kibo core does not export #{fn}; it is older than zk-bundle-v2.16.3",
+                         context: { 'missing' => fn.to_s },
+                         recommendation: 'Use a build of the Kibo binding that ships zk-bundle-v2.16.3 or later.')
+      end
+      unless @caps_checked
+        unless Array(@core.core_capabilities).include?('expected_key_refs')
+          raise KError.new(code: Crypto::KEY_PIN_UNENFORCED,
+                           message: 'the Kibo core does not declare that it enforces expected_key_refs; nothing was sent',
+                           recommendation: 'Use a build of the Kibo binding that ships zk-bundle-v2.16.3 or later.')
+        end
+        @caps_checked = true
+      end
+      @core
+    end
+
+    # [credential, project id, secrets to scrub from messages]
+    def credential(core, crypt, op)
+      t = @federated_token.call(crypt, op)
+      named_provider = t.respond_to?(:provider) ? t.provider : nil
+      if !named_provider.nil? && named_provider.to_s != @provider.to_s
+        raise bad("the platform named provider \"#{named_provider}\"; this client is configured for \"#{@provider}\"", 'provider')
+      end
+
+      named = t.respond_to?(:project_id) ? t.project_id : nil
+      if !named.nil? && !@project_id.nil? && named != @project_id
+        raise bad('the platform named a different project than the one configured', 'projectId')
+      end
+
+      project_id = @project_id.nil? && named.is_a?(String) ? named : @project_id
+      raise bad('project_id is not configured and the platform did not name one', 'projectId') if project_id.nil?
+
+      key = [crypt, op, t.subject].join("\u0000")
+      # A token is fetched on every call (it is bound to the call's crypt and op); the credential from the exchange is
+      # reused until it is close to expiring.
+      cached = @mutex.synchronize { @creds[key] }
+      return [cached, project_id, [t.token, cached.secret]] if cached && cached.expires_at_unix_secs - SKEW_SECS > @now.call
+
+      out = exchange(core, t.token)
+      secret = read(out, :secret)
+      expiry = read(out, :expires_at_unix_secs)
+      unless secret.is_a?(String) && expiry.is_a?(Numeric)
+        raise KError.new(code: 'KIBO_WASM_DECODE_ERROR', message: 'the core returned a credential without secret or expiry')
+      end
+
+      cred = Cred.new(secret, expiry)
+      @mutex.synchronize { @creds[key] = cred }
+      [cred, project_id, [t.token, secret]]
+    end
+
+    # acquire_kms_credential_blocking under a deadline. A blocking native call cannot be interrupted, so it runs on its
+    # own thread and is abandoned when the deadline passes.
+    def exchange(core, token)
+      input = { spec: core_spec, identity_token: token, now_unix_secs: @now.call }
+      worker = Thread.new do
+        Thread.current.report_on_exception = false
+        core.acquire_kms_credential_blocking(input)
+      end
+      unless worker.join(@deadline)
+        worker.kill
+        raise KError.new(code: EXCHANGE_TIMEOUT,
+                         message: "the token exchange with your cloud did not finish within #{@deadline} s",
+                         context: { 'deadlineSecs' => @deadline },
+                         recommendation: "Check that your cloud's token endpoint is reachable from this host.")
+      end
+      worker.value
+    rescue KError => e
+      raise scrub_error(e, [token])
+    rescue StandardError => e
+      raise map_core_error(e, [token])
+    end
+
+    def common(cred, project_id, crypt, context, pin, options)
+      {
+        kms_cred: cred.to_h,
+        provider_config: { aws_region: @provider_config[:aws_region], vault_address: @provider_config[:vault_address] },
+        project_id: project_id,
+        crypt: crypt,
+        context: context,
+        expected_key_refs: pin.dup
+      }
+    end
+
+    def seal(core, cred, project_id, crypt, plaintext, context, pin, options)
+      out = core.app_crypto_seal_blocking(
+        { provider: PROVIDER_WIRE[@provider], posture: @posture.to_s, key_ref: @key_ref.dup,
+          plaintext: plaintext.b }.merge(common(cred, project_id, crypt, context, pin, options))
+      )
+      [to_bytes(read(out, :container))].pack('m0')
+    end
+
+    def open_item(core, cred, project_id, crypt, ciphertext, context, pin, options)
+      container = ciphertext.to_s.unpack1('m0')
+      out = core.app_crypto_open_blocking(
+        { container: container }.merge(common(cred, project_id, crypt, context, pin, options))
+      )
+      to_bytes(read(out, :plaintext))
+    end
+
+    def read(obj, name)
+      if obj.is_a?(Hash)
+        obj.key?(name) ? obj[name] : obj[name.to_s]
+      elsif obj.respond_to?(name)
+        obj.public_send(name)
+      end
+    end
+
+    def to_bytes(value)
+      return value.b if value.is_a?(String)
+      return value.pack('C*') if value.is_a?(Array)
+
+      raise KError.new(code: 'KIBO_WASM_DECODE_ERROR', message: 'the core returned a non-byte value where bytes were expected')
+    end
+
+    # One item's failure stays its own: the core's code passes through ("<CODE>: <message>"; UPSTREAM_KMS_ERROR is your
+    # own KMS failing).
+    def guard(secrets)
+      yield
+    rescue StandardError => e
+      k = map_core_error(e, secrets)
+      { 'ok' => false, 'code' => k.code, 'message' => k.message }
+    end
+
+    def map_core_error(error, secrets)
+      return scrub_error(error, secrets) if error.is_a?(KError)
+
+      raw = scrub(error.message.to_s, secrets)
+      head = /\A([A-Z][A-Z0-9_]*):\s*(.*)\z/m.match(raw)
+      KError.new(code: head ? head[1] : 'KIBO_WASM_ERROR', message: head ? head[2] : raw)
+    end
+
+    def scrub_error(error, secrets)
+      message = scrub(error.message.to_s, secrets)
+      return error if message == error.message.to_s
+
+      KError.new(code: error.code, message: message, context: error.context, recommendation: error.recommendation)
+    end
+
+    def scrub(text, secrets)
+      secrets.compact.reduce(text) { |acc, s| s.to_s.empty? ? acc : acc.gsub(s.to_s, '[redacted]') }
+    end
+  end
+end

data/lib/k9o/kibo_ffi_core.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative 'kerror'
+
+module K9o
+  # The bound Kibo core for K9o::KiboClientCore: it hands the SDK's plain Hashes and Strings to the generated uniffi
+  # binding (+KiboKmsRestFfi+, zk-bundle-v2.16.3 or later) as the typed records, integer enums and federation variant
+  # the binding wants, and turns the binding's errors into the SDK's "CODE: detail" form. There is no cryptography here:
+  # sealing, opening, the key pin and the token exchange all run in the native core. Requiring +k9o+ does not load the
+  # binding; building this object does, and raises a K9o::KError saying what is missing when it cannot.
+  #
+  #   core = K9o::KiboFfiCore.new                                    # binding and library on the default paths
+  #   core = K9o::KiboFfiCore.new(library: '/opt/kibo/libkibo_kms_rest_ffi.so')  # library at an absolute path
+  #
+  # The generated binding opens the native library by its bare name, +kibo_kms_rest_ffi+. Ruby's +ffi+ gem looks for it in
+  # the system library paths (+/opt/homebrew/lib+, +/opt/local/lib+, +/usr/local/lib+, +/usr/lib+, and on Linux the
+  # loader paths such as +LD_LIBRARY_PATH+). macOS does not pass +DYLD_LIBRARY_PATH+ to the system Ruby, so on macOS put
+  # the library in one of those directories or pass +library:+ with its absolute path. +library:+ makes this adapter load
+  # the binding with that path in place of the bare name; the binding file itself is not changed.
+  class KiboFfiCore
+    # Raised from the binding's errors. The message is "<CODE>: <detail>", which KiboClientCore turns into the item's
+    # code and message.
+    class CoreError < StandardError; end
+
+    PROVIDERS = { 'aws-kms' => :AWS_KMS, 'gcp-kms' => :GCP_KMS, 'azure-kv' => :AZURE_KV,
+                  'hashicorp-vault' => :HASHICORP_VAULT }.freeze
+    POSTURES = { 'byok' => :BYOK, 'hyok' => :HYOK }.freeze
+    BINDING_LIB_LINE = /^(\s*)ffi_lib\s+'kibo_kms_rest_ffi'\s*$/.freeze
+    REQUIRED = %i[app_crypto_seal_blocking app_crypto_open_blocking acquire_kms_credential_blocking
+                  core_capabilities].freeze
+
+    # +library+: absolute path of the native library, for a library that is not on the default paths.
+    # +binding_path+: path of the generated +kibo_kms_rest_ffi.rb+, when it is not on the load path. Needed only if
+    #   +KiboKmsRestFfi+ is not already loaded and +require 'kibo_kms_rest_ffi'+ would not find it.
+    # +ffi+: the binding module itself, when you have already loaded it under another name.
+    def initialize(library: nil, binding_path: nil, ffi: nil)
+      @ffi = ffi || load_binding(library, binding_path)
+      REQUIRED.each do |fn|
+        next if @ffi.respond_to?(fn)
+
+        raise unavailable("the loaded KiboKmsRestFfi does not export #{fn}; it is older than zk-bundle-v2.16.3")
+      end
+    end
+
+    def core_capabilities
+      guard { @ffi.core_capabilities }
+    end
+
+    def acquire_kms_credential_blocking(input)
+      guard do
+        @ffi.acquire_kms_credential_blocking(
+          @ffi::FfiFederationInput.new(spec: spec(input[:spec]), identity_token: input[:identity_token],
+                                       now_unix_secs: input[:now_unix_secs])
+        )
+      end
+    end
+
+    def app_crypto_seal_blocking(input)
+      guard do
+        @ffi.app_crypto_seal_blocking(
+          @ffi::AppSealInput.new(
+            provider: enum(@ffi::KmsProvider, PROVIDERS, input[:provider], 'provider'),
+            posture: enum(@ffi::FfiPosture, POSTURES, input[:posture], 'posture'),
+            kms_cred: cred(input[:kms_cred]),
+            key_ref: @ffi::FfiKeyRef.new(version: input[:key_ref][:version], external_ref: input[:key_ref][:external_ref]),
+            provider_config: provider_config(input[:provider_config]),
+            project_id: input[:project_id], crypt: input[:crypt], context: input[:context],
+            plaintext: input[:plaintext], expected_key_refs: input[:expected_key_refs]
+          )
+        )
+      end
+    end
+
+    def app_crypto_open_blocking(input)
+      guard do
+        @ffi.app_crypto_open_blocking(
+          @ffi::AppOpenInput.new(
+            kms_cred: cred(input[:kms_cred]), provider_config: provider_config(input[:provider_config]),
+            project_id: input[:project_id], crypt: input[:crypt], context: input[:context],
+            container: input[:container], expected_key_refs: input[:expected_key_refs]
+          )
+        )
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def unavailable(message)
+      KError.new(code: 'KIBO_WASM_ERROR', message: message,
+                 recommendation: 'Install the generated Kibo binding (kibo_kms_rest_ffi.rb) and the native library ' \
+                                 '(zk-bundle-v2.16.3 or later); see "Encrypt through client.crypto" in the README.')
+    end
+
+    def load_binding(library, binding_path)
+      require 'ffi'
+      existing = loaded_binding
+      return existing if existing
+      return require_binding(binding_path) if library.nil?
+
+      load_with_library(library, binding_path)
+    rescue LoadError => e
+      raise unavailable("the Kibo binding or its native library could not be loaded: #{e.message}")
+    end
+
+    def loaded_binding
+      return nil unless Object.const_defined?(:KiboKmsRestFfi)
+
+      mod = Object.const_get(:KiboKmsRestFfi)
+      mod.respond_to?(:app_crypto_seal_blocking) ? mod : nil
+    end
+
+    def require_binding(binding_path)
+      binding_path ? require(File.expand_path(binding_path)) : require('kibo_kms_rest_ffi')
+      Object.const_get(:KiboKmsRestFfi)
+    end
+
+    # The binding opens +ffi_lib 'kibo_kms_rest_ffi'+ at load. To use an absolute path, the file is read and loaded with
+    # that one line pointing at the path; nothing on disk changes.
+    def load_with_library(library, binding_path)
+      path = File.expand_path(library)
+      raise LoadError, "no native library at #{path}" unless File.file?(path)
+
+      file = binding_path ? File.expand_path(binding_path) : $LOAD_PATH.map { |d| File.join(d.to_s, 'kibo_kms_rest_ffi.rb') }.find { |f| File.file?(f) }
+      raise LoadError, 'cannot find kibo_kms_rest_ffi.rb; pass binding_path: with its path' unless file
+
+      source = File.read(file)
+      raise LoadError, "#{file} does not look like the generated Kibo binding" unless source.match?(BINDING_LIB_LINE)
+
+      # rubocop:disable Security/Eval
+      TOPLEVEL_BINDING.eval(source.sub(BINDING_LIB_LINE) { "#{Regexp.last_match(1)}ffi_lib #{path.inspect}" }, file)
+      # rubocop:enable Security/Eval
+      Object.const_get(:KiboKmsRestFfi)
+    end
+
+    def enum(mod, table, wire, field)
+      name = table[wire.to_s]
+      raise KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: "unknown #{field} #{wire.inspect}", context: { 'field' => field }) unless name
+
+      mod.const_get(name)
+    end
+
+    def cred(h)
+      @ffi::FfiCredential.new(secret: h[:secret], expires_at_unix_secs: h[:expires_at_unix_secs])
+    end
+
+    def provider_config(h)
+      h ||= {}
+      @ffi::FfiProviderConfig.new(aws_region: h[:aws_region], vault_address: h[:vault_address])
+    end
+
+    # The core's federation spec is a variant class per cloud.
+    def spec(s)
+      v = @ffi::FfiFederationSpec
+      case s[:provider].to_s
+      when 'aws' then v::AWS.new(s[:role_arn], s[:session_name], s[:region], s[:key_arn], s[:duration_secs])
+      when 'gcp' then v::GCP.new(s[:audience])
+      when 'azure' then v::AZURE.new(s[:tenant_id], s[:client_id], s[:scope])
+      when 'vault' then v::VAULT.new(s[:vault_addr], s[:mount], s[:role])
+      else
+        raise KError.new(code: 'K9O_INVALID_FIELD_VALUE', message: "unknown federation provider #{s[:provider].inspect}",
+                         context: { 'field' => 'federation.provider' })
+      end
+    end
+
+    # The binding's error classes keep the code and detail as readers; their +message+ is not "CODE: detail".
+    def guard
+      yield
+    rescue @ffi::ZkFfiUniffiError::Platform, @ffi::ZkFfiUniffiError::PostureViolation => e
+      raise CoreError, "#{e.code}: #{e.detail}"
+    rescue @ffi::ZkFfiUniffiError::UpstreamKms => e
+      raise CoreError, "UPSTREAM_KMS_ERROR: #{e.detail}"
+    end
+  end
+end

data/lib/k9o/locate.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module K9o
+  # Locating the end user's region for password sign-in.
+  #
+  # K9o::Region finds the org's regional API host. An end user can live in another region of the project, so
+  # +gate.sign_in+ first asks the project which region holds the address
+  # (+POST /@<project>/gate/locate { email }+ at that regional base, with no credential) and sends the password to the
+  # origin it names. The answer is the same for a known and an unknown address.
+  #
+  # Rules:
+  # - The located origin is used for that one attempt. It is never cached. The one thing kept is a hint per refresh
+  #   token (at most 64, in memory), so that refresh and sign-out reach the region that issued the session; a stale
+  #   hint gets a 401.
+  # - An origin is used only if it is https (http only when the base is itself http on a loopback host and the origin is
+  #   loopback too), has no userinfo, port, path, query or fragment, and its host is exactly the base host's org,
+  #   family and apex with the region code ([a-z]{2}\d{2}) added or swapped in the gateway label, and that code equals
+  #   the answer's +region+. Anything else, or +origin: null+, means the base is used. A password never goes to a host
+  #   that fails this.
+  module Locate
+    REGION_CODE = /\A[a-z]{2}\d{2}\z/.freeze
+    HINT_LIMIT = 64
+    HINT_LOCK = Mutex.new
+    HINTS = {}
+
+    module_function
+
+    def loopback?(host)
+      h = host.to_s.downcase
+      h == 'localhost' || h.end_with?('.localhost') || h == '127.0.0.1' || h == '[::1]' || h == '::1'
+    end
+
+    # The origin the credential goes to: the located one if it passes the rule, else +base+. Pure; never raises.
+    # +answer+ is the +data+ of the locate envelope.
+    def choose_origin(base, answer)
+      return base unless answer.is_a?(Hash)
+
+      region = answer['region'] || answer[:region]
+      origin = answer['origin'] || answer[:origin]
+      return base unless origin.is_a?(String) && region.is_a?(String) && REGION_CODE.match?(region)
+
+      b = URI.parse(base)
+      u = URI.parse(origin)
+      return base if b.host.nil? || u.host.nil? || !u.scheme.is_a?(String)
+      return base unless u.userinfo.nil? && u.query.nil? && u.fragment.nil?
+      return base unless u.port == u.default_port
+      return base unless u.path.empty? || u.path == '/'
+
+      bs = b.scheme.to_s.downcase
+      us = u.scheme.to_s.downcase
+      unless us == 'https' || (us == 'http' && bs == 'http' && loopback?(b.host) && loopback?(u.host))
+        return base
+      end
+
+      bh = b.host.downcase
+      uh = u.host.downcase
+      return "#{bs}://#{bh}#{b.port == b.default_port ? '' : ":#{b.port}"}" if us == bs && uh == bh && u.port == b.port
+
+      from = UrlGrammar.parse_api_host(bh)
+      to = UrlGrammar.parse_api_host(uh)
+      return base if from.nil? || to.nil? || to.region != region
+      return base unless from.org_slug == to.org_slug && from.family == to.family && from.apex == to.apex
+
+      "#{us}://#{uh}"
+    rescue URI::Error, ArgumentError
+      base
+    end
+
+    # Ask the project which region holds +email+ and return the origin the credential goes to. A 404 from the door
+    # means the locate door is off and the base is used. Any other non-2xx answer (429, 503, anything else) raises as any other gateway error does, and nothing is sent after it. A 2xx
+    # answer that cannot be read means the base is used.
+    def origin_for(config, email, path)
+      base = Region.resolve_origin(config).sub(%r{/+\z}, '')
+      begin
+        env = HttpTransport.request(config: config, method: 'POST', path: path, body: { 'email' => email },
+                                    authenticated: false)
+      rescue KError => e
+        # 404: the locate door is off, so the base is used.
+        raise unless e.status == 404 || (e.code == 'K9O_INTERNAL_ERROR' && e.status.to_i.between?(200, 299))
+
+        return base
+      end
+      choose_origin(base, env.data)
+    end
+
+    # Remember which origin issued the session with this refresh token (a hint, not authority).
+    def remember(refresh_token, origin)
+      return unless refresh_token.is_a?(String) && !refresh_token.empty?
+
+      HINT_LOCK.synchronize do
+        HINTS.delete(refresh_token)
+        HINTS[refresh_token] = origin
+        HINTS.delete(HINTS.keys.first) while HINTS.size > HINT_LIMIT
+      end
+    end
+
+    def hint(refresh_token)
+      HINT_LOCK.synchronize { HINTS[refresh_token] }
+    end
+
+    def forget(refresh_token)
+      HINT_LOCK.synchronize { HINTS.delete(refresh_token) }
+    end
+
+    # A refresh answers with a new refresh token and the old one stops working: the hint follows the session. Data
+    # without a new token changes nothing.
+    def rotate(old_refresh_token, data)
+      token = data.is_a?(Hash) ? data['refreshToken'] : nil
+      origin = hint(old_refresh_token)
+      return unless token.is_a?(String) && !token.empty? && origin
+
+      forget(old_refresh_token)
+      remember(token, origin)
+    end
+  end
+end