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

data/lib/k9o/kerror.rb

@@ -8,8 +8,12 @@ module K9o
   # Code-narrowing: callers rescue K9o::KError and switch on e.code.
   class KError < StandardError
     attr_reader :code, :context, :recommendation, :status, :request_id
+    # Seconds the gateway asks the caller to wait before retrying, or nil.
+    # Informational: the SDK's own retry behaviour does not read it.
+    attr_reader :retry_after_sec
 
-    def initialize(code:, message:, context: {}, recommendation: nil, status: nil, request_id: nil)
+    def initialize(code:, message:, context: {}, recommendation: nil, status: nil, request_id: nil,
+                   retry_after_sec: nil)
       super(message)
       @code = code
       @message_text = message  # avoid infinite recursion in to_s (Exception#message calls to_s)
@@ -17,13 +21,21 @@ module K9o
       @recommendation = recommendation
       @status = status
       @request_id = request_id
+      @retry_after_sec = retry_after_sec
+    end
+
+    # The step-up challenge a 401 K9O_STEP_UP_REQUIRED carries (context.stepUp) as a K9o::Keys::StepUpChallenge
+    # (+scope_set_root+, +nonce+, +min_tier+, +methods+, +max_age_sec+, +single_use+, +rp_id+), or nil.
+    def step_up
+      Keys::StepUp.challenge_from(@context)
     end
 
     def with_recommendation(rec)
       KError.new(
         code: @code, message: @message_text,
         context: @context, recommendation: rec,
-        status: @status, request_id: @request_id
+        status: @status, request_id: @request_id,
+        retry_after_sec: @retry_after_sec
       )
     end
 
@@ -38,15 +50,55 @@ module K9o
     end
 
     # Rehydrate a wire KError payload into a typed K9o::KError.
-    def self.from_wire(wire, status)
+    # +retry_after_header+ is the response's Retry-After header (whole seconds); it is used when the body's
+    # recommendation carries no +retryAfterSec+. +request_id_header+ is the response's x-k9o-request-id header;
+    # it is used when the body carries no request id.
+    def self.from_wire(wire, status, retry_after_header: nil, request_id_header: nil)
       KError.new(
         code: wire['code'] || 'K9O_INTERNAL_ERROR',
         message: wire['message'] || '',
         context: wire['context'] || {},
-        recommendation: wire['recommendation'],
+        recommendation: recommendation_text(wire['recommendation']),
         status: status,
-        request_id: wire['requestId'] || wire['request_id']
+        request_id: wire['requestId'] || wire['request_id'] || request_id_from_header(request_id_header),
+        retry_after_sec: retry_after(wire['recommendation']) || retry_after_from_header(retry_after_header)
       )
     end
+
+    # The gateway's request id from the x-k9o-request-id header value, or nil when absent or blank.
+    def self.request_id_from_header(value)
+      return nil unless value.is_a?(String) && !value.strip.empty?
+
+      value.strip
+    end
+
+    # Whole seconds from a Retry-After header value; an HTTP date or anything else gives nil.
+    def self.retry_after_from_header(value)
+      return nil unless value.is_a?(String) && value.strip.match?(/\A\d+\z/)
+
+      value.strip.to_i
+    end
+
+    # The gateway sends `recommendation` as null, a string, or an object such
+    # as {"action": "..."} or {"retryAfterSec": 30, "note": "..."}. A string is
+    # kept; an object gives its `action`, else its `note`, when a string;
+    # anything else gives nil.
+    def self.recommendation_text(raw)
+      return raw if raw.is_a?(String)
+      return nil unless raw.is_a?(Hash)
+
+      [raw['action'], raw['note']].find { |v| v.is_a?(String) }
+    end
+
+    # `retryAfterSec` from an object recommendation when a finite number >= 0.
+    def self.retry_after(raw)
+      return nil unless raw.is_a?(Hash)
+
+      n = raw['retryAfterSec']
+      return nil unless n.is_a?(Numeric) && !n.is_a?(Complex) && n >= 0
+      return nil if n.respond_to?(:finite?) && !n.finite?
+
+      n
+    end
   end
 end

data/lib/k9o/keys.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module K9o
+  # client.keys: the project's encryption keys. Metadata only: no key material is ever returned.
+  #
+  #   list(status: nil)            GET  /@<slug>/vault/keys           data: { "items" => [key] } (not paged)
+  #   get(key_id)                  GET  /@<slug>/vault/keys/<id>      data: key
+  #   rotate(key_id, step_up: nil) POST /@<slug>/vault/keys/<id>/rotate
+  #
+  # A key is { "id", "version", "status", "custodyMode", "createdAt", "rotatedAt", "byokRef", "hyokRef" }.
+  # Reading needs PROJECT_ADMIN or PROJECT_AUDITOR; rotating needs PROJECT_ADMIN and a fresh step-up proof.
+  # A person's credential only: service, workload, extension and end-user tokens are refused (403).
+  class Keys
+    STATUSES = %w[active all].freeze
+    STEP_UP_HEADER = 'x-k9o-step-up-proof'
+
+    def initialize(config)
+      @config = config
+    end
+
+    # The project's keys. Only the active key by default; +status:+ "all" adds the rotating and revoked versions.
+    # The list is not paged: +data+ is { "items" => [key] } and nothing else.
+    def list(status: nil)
+      query = {}
+      query['status'] = ApprovalChecks.enum!(status, STATUSES, 'status') unless status.nil?
+      envelope = call('GET', '', query: query)
+      data = envelope.data
+      return envelope unless data.is_a?(Hash) && data.key?('nextCursor')
+
+      Envelope.new(data: data.reject { |k, _| k == 'nextCursor' }, meta: envelope.meta)
+    end
+
+    def get(key_id)
+      call('GET', "/#{ApprovalChecks.id_segment(key_id, 'key')}")
+    end
+
+    # Rotate the active key: every data key is re-wrapped under a new version and the old version is revoked.
+    # +data+ is { "keyId", "previousVersion", "newVersion", "status" => "rotated" }.
+    #
+    # Rotation needs a fresh step-up proof. The first request answers 401 K9O_STEP_UP_REQUIRED with a challenge
+    # (K9o::KError#step_up, a K9o::Keys::StepUpChallenge). Pass +step_up:+ a callable and the SDK hands it the
+    # challenge, the HTTP method and the URL being called, expects { method:, proof: } back (+method+ is one of the
+    # challenge's +methods+; +proof+ is that method's own proof, for DPoP bound to this method and URL) and sends the
+    # same request again with the +x-k9o-step-up-proof+ header: base64url(JSON { scopeSetRoot, nonce, method, proof }).
+    # It retries exactly once. Without a hook the K9O_STEP_UP_REQUIRED error is raised and carries the challenge.
+    # An error from your hook, a second 401 or any other failure of the retry is raised as it is. The proof is never
+    # logged. Nothing in the platform mints the proof for you.
+    #
+    # Other errors (all K9o::KError): 409 K9O_STATE_CONFLICT with context reason "rotation_in_flight" or
+    # "key_not_active"; 429 K9O_RATE_LIMITED with reason "rotation_rate_cap" (at most 3 rotations per rolling 24 hours;
+    # +retry_after_sec+ says when the next one is possible) or "key_service_busy". A refused rotation does not use up
+    # a proof. +headers:+ adds request headers. The call is never retried otherwise.
+    def rotate(key_id, step_up: nil, headers: nil)
+      tail = "/#{ApprovalChecks.id_segment(key_id, 'key')}/rotate"
+      unless step_up.nil? || step_up.respond_to?(:call)
+        raise ApprovalChecks.invalid('step_up must respond to call(challenge, method, url)')
+      end
+
+      begin
+        call('POST', tail, headers: headers)
+      rescue KError => e
+        raise unless step_up && e.code == 'K9O_STEP_UP_REQUIRED' && e.status == 401
+
+        challenge = e.step_up
+        raise unless challenge
+
+        method = 'POST'
+        url = "#{Region.resolve_origin(@config).sub(%r{/\z}, '')}#{UrlGrammar.project_path(slug_for_keys, "vault/keys#{tail}")}"
+        answer = step_up.call(challenge, method, url)
+        proof_header = StepUp.header(challenge, answer)
+        call('POST', tail, headers: (headers || {}).merge(STEP_UP_HEADER => proof_header))
+      end
+    end
+
+    # The step-up challenge from a 401 K9O_STEP_UP_REQUIRED (context.stepUp).
+    StepUpChallenge = Struct.new(:scope_set_root, :nonce, :min_tier, :methods, :max_age_sec, :single_use, :rp_id,
+                                 keyword_init: true)
+
+    module StepUp
+      module_function
+
+      # The challenge in an error's context, or nil.
+      def challenge_from(context)
+        raw = context.is_a?(Hash) ? (context['stepUp'] || context[:stepUp]) : nil
+        return nil unless raw.is_a?(Hash)
+
+        root = raw['scopeSetRoot']
+        nonce = raw['nonce']
+        return nil unless root.is_a?(String) && nonce.is_a?(String)
+
+        StepUpChallenge.new(scope_set_root: root, nonce: nonce, min_tier: raw['minTier'],
+                            methods: Array(raw['methods']), max_age_sec: raw['maxAgeSec'],
+                            single_use: raw['singleUse'], rp_id: raw['rpId'])
+      end
+
+      # base64url (no padding) of JSON { scopeSetRoot, nonce, method, proof }, from the hook's answer.
+      def header(challenge, answer)
+        unless answer.is_a?(Hash)
+          raise ApprovalChecks.invalid('the step_up hook must return { method:, proof: }')
+        end
+
+        method = answer[:method] || answer['method']
+        proof = answer[:proof] || answer['proof']
+        unless method.is_a?(String) && !method.empty? && proof.is_a?(String) && !proof.empty?
+          raise ApprovalChecks.invalid('the step_up hook must return a method and a proof, both non-empty strings')
+        end
+        unless challenge.methods.empty? || challenge.methods.include?(method)
+          raise ApprovalChecks.invalid("step-up method must be one of: #{challenge.methods.join(', ')}")
+        end
+
+        json = JSON.generate('scopeSetRoot' => challenge.scope_set_root, 'nonce' => challenge.nonce,
+                             'method' => method, 'proof' => proof)
+        [json].pack('m0').tr('+/', '-_').delete('=')
+      end
+    end
+
+    private
+
+    def slug_for_keys
+      Studio.require_project_slug(@config, 'keys')
+    end
+
+    def call(method, tail, query: nil, headers: nil)
+      slug = slug_for_keys
+      HttpTransport.request(config: @config, method: method, path: UrlGrammar.project_path(slug, "vault/keys#{tail}"),
+                            query: query, headers: headers)
+    end
+  end
+end

data/lib/k9o/kibo.rb

@@ -97,14 +97,14 @@ module K9o
       case e
       when KiboKmsRestFfi::ZkFfiUniffiError::PostureViolation
         K9o::KError.new(
-          code: e.code, message: e.message,
+          code: e.code, message: e.detail,
           context: { dimension: e.dimension, requested: e.requested, declared: e.declared }
         )
       when KiboKmsRestFfi::ZkFfiUniffiError::Platform
-        K9o::KError.new(code: e.code, message: e.message)
+        K9o::KError.new(code: e.code, message: e.detail)
       when KiboKmsRestFfi::ZkFfiUniffiError::UpstreamKms
         # Customer's own KMS failed — no K9O_* code (outside the platform error namespace).
-        K9o::KError.new(code: 'UPSTREAM_KMS_ERROR', message: e.message)
+        K9o::KError.new(code: 'UPSTREAM_KMS_ERROR', message: e.detail)
       else
         K9o::KError.new(code: 'KIBO_FFI_ERROR', message: e.message)
       end

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