k9o 1.2.0-aarch64-linux → 1.5.0-aarch64-linux

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

data/lib/k9o/me.rb

@@ -1,23 +1,21 @@
 # frozen_string_literal: true
 
 module K9o
-  # Operator-self namespace — k9o.me.*. Cross-org;
-  # org-plane routes under /me. Sub-namespaces: profile / sessions /
-  # api_tokens / notifications / audit_log / data_export.
+  # Operator-self namespace — k9o.me.*. Cross-org; org-plane routes under /me.
+  # Sub-namespaces: profile / sessions / api_tokens.
   class Me
-    attr_reader :profile, :sessions, :api_tokens, :notifications, :audit_log, :data_export
+    attr_reader :profile, :sessions, :api_tokens
 
     def initialize(config)
       @profile = Profile.new(config)
       @sessions = Sessions.new(config)
       @api_tokens = ApiTokens.new(config)
-      @notifications = Notifications.new(config)
-      @audit_log = AuditLog.new(config)
-      @data_export = DataExport.new(config)
     end
 
     # k9o.me.profile.*
     class Profile
+      PATCH_FIELDS = { display_name: 'displayName', locale: 'locale', timezone: 'timezone' }.freeze
+
       def initialize(config)
         @config = config
       end
@@ -26,9 +24,17 @@ module K9o
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me'))
       end
 
-      def update(display_name: nil)
-        HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('me'),
-                              body: { 'displayName' => display_name })
+      # PATCH /me. Pass only the fields to change (display_name, locale, timezone); an explicit +nil+ is sent as
+      # null.
+      def update(**fields)
+        patch = {}
+        fields.each do |key, value|
+          wire = PATCH_FIELDS[key]
+          raise ArgumentError, "unknown profile field: #{key}" if wire.nil?
+
+          patch[wire] = value
+        end
+        HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('me'), body: patch)
       end
     end
 
@@ -42,13 +48,15 @@ module K9o
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/sessions'))
       end
 
+      # POST /auth/sessions/<id>/revoke
       def revoke(session_id)
-        HttpTransport.request(config: @config, method: 'DELETE',
-                              path: UrlGrammar.org_path("me/sessions/#{enc(session_id)}"))
+        HttpTransport.request(config: @config, method: 'POST',
+                              path: UrlGrammar.org_path("auth/sessions/#{enc(session_id)}/revoke"))
       end
 
+      # POST /me/sessions/revoke-all
       def revoke_all
-        HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.org_path('me/sessions'))
+        HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('me/sessions/revoke-all'))
       end
 
       private
@@ -68,10 +76,12 @@ module K9o
         HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/api-tokens'))
       end
 
-      def create(name:, expires_in_days: nil, scope: nil)
-        body = { 'name' => name }
-        body['expiresInDays'] = expires_in_days if expires_in_days
-        body['scope'] = scope if scope
+      # POST /me/api-tokens { label, scopeManifest, ttlSeconds? }. +scope_manifest+ is a Hash with the gateway's keys
+      # (each may be nil for "no restriction"): 'tier' (readonly / readwrite / admin, required), 'projects', 'resourceClasses',
+      # 'collections', 'cidrs'. The response carries the token's plaintext once.
+      def create(label:, scope_manifest:, ttl_seconds: nil)
+        body = { 'label' => label, 'scopeManifest' => scope_manifest }
+        body['ttlSeconds'] = ttl_seconds unless ttl_seconds.nil?
         HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('me/api-tokens'), body: body)
       end
 
@@ -86,75 +96,5 @@ module K9o
         ::URI.encode_www_form_component(s)
       end
     end
-
-    # k9o.me.notifications.*
-    class Notifications
-      def initialize(config)
-        @config = config
-      end
-
-      def list(unread_only: nil, limit: nil, cursor: nil)
-        q = {}
-        q['unreadOnly'] = unread_only unless unread_only.nil?
-        q['limit'] = limit if limit
-        q['cursor'] = cursor unless cursor.nil?
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/notifications'), query: q)
-      end
-
-      def mark_read(notification_id)
-        HttpTransport.request(config: @config, method: 'PATCH',
-                              path: UrlGrammar.org_path("me/notifications/#{enc(notification_id)}"), body: { 'read' => true })
-      end
-
-      def mark_all_read
-        HttpTransport.request(config: @config, method: 'PATCH', path: UrlGrammar.org_path('me/notifications'),
-                              body: { 'read' => true })
-      end
-
-      private
-
-      def enc(s)
-        ::URI.encode_www_form_component(s)
-      end
-    end
-
-    # k9o.me.audit_log.*
-    class AuditLog
-      def initialize(config)
-        @config = config
-      end
-
-      def query(since: nil, until_: nil, type: nil, limit: nil, cursor: nil)
-        q = {}
-        q['since'] = since if since
-        q['until'] = until_ if until_
-        q['type'] = type if type
-        q['limit'] = limit if limit
-        q['cursor'] = cursor if cursor
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/audit-log'), query: q)
-      end
-    end
-
-    # k9o.me.data_export.*
-    class DataExport
-      def initialize(config)
-        @config = config
-      end
-
-      def request(format: 'json')
-        HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('me/data-export'),
-                              body: { 'format' => format })
-      end
-
-      def status(job_id)
-        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path("me/data-export/#{enc(job_id)}"))
-      end
-
-      private
-
-      def enc(s)
-        ::URI.encode_www_form_component(s)
-      end
-    end
   end
 end