k9o 1.0.0

data/lib/k9o/http_transport.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require_relative 'multipart'
+
+module K9o
+  # Retry + backoff policy (ch13 §7.1). Applied to idempotent methods
+  # (GET/HEAD/OPTIONS/DELETE) on transient failures only (transport error /
+  # 502 / 503 / 504 / 429); semantic 4xx and non-idempotent methods are
+  # never retried.
+  class RetryConfig
+    attr_reader :max_retries, :backoff, :initial_delay_ms, :max_delay_ms
+
+    # backoff: 'exponential' | 'linear' | 'none'
+    def initialize(max_retries: 3, backoff: 'exponential', initial_delay_ms: 100, max_delay_ms: 5000)
+      @max_retries = max_retries
+      @backoff = backoff
+      @initial_delay_ms = initial_delay_ms
+      @max_delay_ms = max_delay_ms
+    end
+
+    def self.default
+      new
+    end
+  end
+
+  # Per-instance HTTP config bound on K9oClient.
+  class HttpClientConfig
+    attr_reader :base_url, :api_key, :org_slug, :project_slug, :default_headers, :http_client, :retry_config,
+                :region_mutex
+    # Cached regional origin (see K9o::Region); nil until a definite answer.
+    attr_accessor :regional_origin
+
+    def initialize(base_url:, api_key: nil, org_slug: nil, project_slug: nil, default_headers: {}, http_client: nil,
+                   retry_config: nil)
+      @base_url = base_url
+      @api_key = api_key
+      @org_slug = org_slug
+      @project_slug = project_slug
+      @default_headers = default_headers.freeze
+      @http_client = http_client
+      @retry_config = retry_config
+      @region_mutex = Mutex.new
+      @regional_origin = nil
+    end
+  end
+
+  # HTTP transport using Net::HTTP stdlib.
+  module HttpTransport
+    RETRYABLE_METHODS = %w[GET HEAD OPTIONS DELETE].freeze
+    RETRYABLE_STATUS = [502, 503, 504, 429].freeze
+
+    module_function
+
+    # Issue a request with retry on transient failures. Idempotent methods
+    # are retried with backoff per config.retry_config (ch13 §7.1);
+    # semantic / non-idempotent failures raise immediately.
+    #
+    # `headers:` carries per-call header overrides on top of
+    # `config.default_headers` — e.g. `client.kibo.vault.secrets.reveal`'s
+    # single-use `X-K9O-Reveal-Challenge` header, which is per-request rather
+    # than a client-wide default.
+    #
+    # `multipart:` is an array of parts (see K9o::Multipart) sent as a
+    # multipart/form-data body instead of JSON.
+    #
+    # `authenticated: false` sends NO credential: no api_key bearer, and any
+    # authorization / cookie header from `default_headers` or `headers:` is dropped.
+    def request(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil)
+      retry_with_backoff(method, config.retry_config || RetryConfig.default) do
+        request_once(config: config, method: method, path: path, body: body, query: query, headers: headers,
+                     authenticated: authenticated, multipart: multipart)
+      end
+    end
+
+    # Run a block with retry-with-backoff. Extracted so the retry policy is
+    # unit-testable without a live HTTP round-trip.
+    def retry_with_backoff(method, retry_config)
+      last_error = nil
+      attempt = 0
+      while attempt <= retry_config.max_retries
+        begin
+          return yield
+        rescue KError => e
+          last_error = e
+          raise e if attempt == retry_config.max_retries || !retryable?(e, method)
+
+          delay_ms = compute_delay_ms(retry_config, attempt)
+          sleep(delay_ms / 1000.0) if delay_ms > 0
+          attempt += 1
+        end
+      end
+      raise last_error
+    end
+
+    def retryable?(error, method)
+      return false unless RETRYABLE_METHODS.include?(method.to_s.upcase)
+      return true if error.code == 'K9O_UPSTREAM_UNAVAILABLE'
+
+      RETRYABLE_STATUS.include?(error.status)
+    end
+
+    def compute_delay_ms(config, attempt)
+      return 0 if config.backoff == 'none'
+
+      base = if config.backoff == 'linear'
+               config.initial_delay_ms * (attempt + 1)
+             else
+               config.initial_delay_ms * (2**attempt)
+             end
+      capped = [base, config.max_delay_ms].min
+      jitter = capped * 0.25 * (rand * 2 - 1)
+      [(capped + jitter).to_i, 0].max
+    end
+
+    # Single-attempt request. `request` wraps this in retry-with-backoff.
+    def request_once(config:, method:, path:, body: nil, query: nil, headers: nil, authenticated: true, multipart: nil)
+      url = "#{Region.resolve_origin(config).sub(%r{/\z}, '')}#{path}"
+      if query && !query.empty?
+        url += '?' + URI.encode_www_form(query)
+      end
+
+      uri = URI.parse(url)
+      http = config.http_client || ::Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == 'https')
+      http.read_timeout = 30
+
+      req_class = case method.to_s.upcase
+                  when 'GET' then ::Net::HTTP::Get
+                  when 'POST' then ::Net::HTTP::Post
+                  when 'PATCH' then ::Net::HTTP::Patch
+                  when 'PUT' then ::Net::HTTP::Put
+                  when 'DELETE' then ::Net::HTTP::Delete
+                  else raise ArgumentError, "Unsupported method: #{method}"
+                  end
+
+      req = req_class.new(uri.request_uri)
+      req['accept'] = 'application/json'
+      config.default_headers.each { |k, v| req[k] = v }
+      req['x-k9o-project-slug'] = config.project_slug if config.project_slug
+      headers&.each { |k, v| req[k] = v }
+      req['x-k9o-org-slug'] = config.org_slug if config.org_slug
+      if authenticated
+        req['authorization'] = "Bearer #{config.api_key}" if config.api_key
+      else
+        req.delete('authorization')
+        req.delete('cookie')
+      end
+
+      if multipart
+        # multipart/form-data: the encoder sets the boundary; never force JSON.
+        data, content_type = Multipart.encode(multipart)
+        req['content-type'] = content_type
+        req.body = data
+      elsif body
+        req['content-type'] = 'application/json'
+        req.body = JSON.dump(body)
+      end
+
+      begin
+        response = http.request(req)
+      rescue => e
+        raise KError.new(
+          code: 'K9O_UPSTREAM_UNAVAILABLE',
+          message: "Network error reaching #{url}: #{e.message}",
+          context: { url: url },
+          recommendation: 'Check connectivity to the gateway; retry with backoff if transient.'
+        )
+      end
+
+      status = response.code.to_i
+
+      return Envelope.new(data: nil, meta: Meta.new) if status == 204
+
+      begin
+        parsed = JSON.parse(response.body || '')
+      rescue JSON::ParserError => e
+        raise KError.new(
+          code: 'K9O_INTERNAL_ERROR',
+          message: "Failed to parse JSON response from #{url}: #{e.message}",
+          context: { url: url, status: status },
+          status: status
+        )
+      end
+
+      if status >= 200 && status < 300
+        unless parsed.is_a?(Hash) && parsed.key?('data') && parsed.key?('meta')
+          raise KError.new(
+            code: 'K9O_INTERNAL_ERROR',
+            message: "Malformed envelope from #{url}: expected {data, meta}",
+            context: { url: url, status: status },
+            status: status
+          )
+        end
+        return Envelope.from_wire(parsed)
+      end
+
+      if parsed.is_a?(Hash) && parsed['code'].is_a?(String) && parsed['message'].is_a?(String)
+        raise KError.from_wire(parsed, status)
+      end
+
+      raise KError.new(
+        code: 'K9O_INTERNAL_ERROR',
+        message: "Upstream returned #{status} with non-KError body",
+        context: { url: url, status: status },
+        status: status
+      )
+    end
+
+    # Open an SSE stream and return an Enumerator yielding decoded `data:`
+    # payloads (parsed JSON). Used by Compute LLMs #invoke_stream (ch07
+    # §10.2) + Realtime #subscribe SSE transport (ch07 §11.3). The [DONE]
+    # sentinel terminates the stream; non-2xx raises KError before any
+    # event is yielded.
+    #
+    # Per ch13 §8 the Ruby async-iteration idiom is Enumerator — caller
+    # writes `client.compute.llms.invoke_stream(...).each { |chunk| ... }`.
+    def stream_sse(config:, method:, path:, body: nil, query: nil)
+      url = "#{Region.resolve_origin(config).sub(%r{/\z}, '')}#{path}"
+      if query && !query.empty?
+        url += '?' + URI.encode_www_form(query)
+      end
+      uri = URI.parse(url)
+
+      Enumerator.new do |yielder|
+        http = config.http_client || ::Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == 'https')
+        http.read_timeout = 300
+
+        req_class = case method.to_s.upcase
+                    when 'GET' then ::Net::HTTP::Get
+                    when 'POST' then ::Net::HTTP::Post
+                    else raise ArgumentError, "Unsupported stream method: #{method}"
+                    end
+        req = req_class.new(uri.request_uri)
+        req['accept'] = 'text/event-stream'
+        config.default_headers.each { |k, v| req[k] = v }
+        req['x-k9o-project-slug'] = config.project_slug if config.project_slug
+        req['x-k9o-org-slug'] = config.org_slug if config.org_slug
+        req['authorization'] = "Bearer #{config.api_key}" if config.api_key
+        if body
+          req['content-type'] = 'application/json'
+          req.body = JSON.dump(body)
+        end
+
+        begin
+          http.request(req) do |response|
+            status = response.code.to_i
+            if status < 200 || status >= 300
+              raw = +''
+              response.read_body { |c| raw << c }
+              parsed = begin
+                JSON.parse(raw)
+              rescue JSON::ParserError
+                nil
+              end
+              if parsed.is_a?(Hash) && parsed['code'].is_a?(String) && parsed['message'].is_a?(String)
+                raise KError.from_wire(parsed, status)
+              end
+
+              raise KError.new(
+                code: 'K9O_INTERNAL_ERROR',
+                message: "Upstream returned #{status} opening stream",
+                context: { url: url, status: status },
+                status: status
+              )
+            end
+
+            buffer = +''
+            data_lines = []
+            flush = lambda do
+              return true if data_lines.empty?
+
+              payload = data_lines.join("\n")
+              data_lines = []
+              return false if payload == '[DONE]'
+
+              begin
+                yielder << JSON.parse(payload)
+              rescue JSON::ParserError => e
+                raise KError.new(code: 'K9O_INTERNAL_ERROR', message: "failed to decode stream chunk: #{e.message}")
+              end
+              true
+            end
+
+            response.read_body do |chunk|
+              buffer << chunk
+              while (idx = buffer.index("\n"))
+                line = buffer.slice!(0..idx).chomp
+                if line.empty?
+                  break unless flush.call
+                elsif line.start_with?(':')
+                  next
+                elsif line.start_with?('data:')
+                  rest = line[5..]
+                  rest = rest[1..] if rest.start_with?(' ')
+                  data_lines << rest
+                end
+              end
+            end
+            flush.call
+          end
+        rescue KError
+          raise
+        rescue StandardError => e
+          raise KError.new(
+            code: 'K9O_UPSTREAM_UNAVAILABLE',
+            message: "Network error reaching #{url}: #{e.message}",
+            context: { url: url },
+            recommendation: 'Check connectivity to the gateway; retry with backoff if transient.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/k9o/kerror.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module K9o
+  # KError — the closed-taxonomy error raised by every k9o surface
+  # on non-2xx gateway responses or SDK-side validation failures.
+  #
+  # Ruby idiomatic shape: raise K9o::KError.
+  # Code-narrowing: callers rescue K9o::KError and switch on e.code.
+  class KError < StandardError
+    attr_reader :code, :context, :recommendation, :status, :request_id
+
+    def initialize(code:, message:, context: {}, recommendation: nil, status: nil, request_id: nil)
+      super(message)
+      @code = code
+      @message_text = message  # avoid infinite recursion in to_s (Exception#message calls to_s)
+      @context = context.freeze
+      @recommendation = recommendation
+      @status = status
+      @request_id = request_id
+    end
+
+    def with_recommendation(rec)
+      KError.new(
+        code: @code, message: @message_text,
+        context: @context, recommendation: rec,
+        status: @status, request_id: @request_id
+      )
+    end
+
+    # Override message to return the raw text (Exception's default calls to_s
+    # which causes infinite recursion since we override to_s).
+    def message
+      @message_text
+    end
+
+    def to_s
+      @status ? "[#{@code}] #{@message_text} (status=#{@status})" : "[#{@code}] #{@message_text}"
+    end
+
+    # Rehydrate a wire KError payload into a typed K9o::KError.
+    def self.from_wire(wire, status)
+      KError.new(
+        code: wire['code'] || 'K9O_INTERNAL_ERROR',
+        message: wire['message'] || '',
+        context: wire['context'] || {},
+        recommendation: wire['recommendation'],
+        status: status,
+        request_id: wire['requestId'] || wire['request_id']
+      )
+    end
+  end
+end

data/lib/k9o/kibo.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'kerror'
+
+module K9o
+  # Zero-Knowledge BYOK/HYOK vault crypto — +K9o::Kibo.encrypt+ / +.decrypt+.
+  #
+  # Thin wrapper over the bound core (+kibo-kms-rest-ffi+, piece C) via uniffi.
+  # ZERO crypto here: every wrap/unwrap, envelope framing, posture-floor
+  # enforcement, and KMS round-trip lives in the audited Rust core.
+  #
+  # Ruby has no async runtime, so this calls the SYNC +zk_encrypt_blocking+ /
+  # +zk_decrypt_blocking+ exports — which drive the SAME canonical async op to
+  # completion on a process-wide tokio runtime inside the core (crypto-identical
+  # to the async exports the async-native languages use; W7C-confirmed neutral).
+  #
+  # The generated uniffi binding + native lib (+lib/k9o/_ffi/+) are build
+  # artifacts (CI-injected per platform; gitignored). On a platform/Ruby without
+  # the lib, +require+ still succeeds and +encrypt+/+decrypt+ raise a clear
+  # +K9o::KError+ — so loading +k9o+ never breaks for the rest of the SDK.
+  module Kibo
+    # Attempt to load the native binding; never raises at require time.
+    NATIVE_AVAILABLE =
+      begin
+        require_relative '_ffi/kibo_kms_rest_ffi'
+        true
+      rescue LoadError
+        false
+      end
+
+    # Re-export the binding's input/output + enum types for ergonomic use
+    # (+K9o::Kibo::EncryptInput+, +K9o::Kibo::FfiPosture::BYOK+, …).
+    if NATIVE_AVAILABLE
+      EncryptInput          = KiboKmsRestFfi::EncryptInput
+      DecryptInput          = KiboKmsRestFfi::DecryptInput
+      EncryptOutput         = KiboKmsRestFfi::EncryptOutput
+      DecryptOutput         = KiboKmsRestFfi::DecryptOutput
+      FfiCredential         = KiboKmsRestFfi::FfiCredential
+      FfiKeyRef             = KiboKmsRestFfi::FfiKeyRef
+      FfiProviderConfig     = KiboKmsRestFfi::FfiProviderConfig
+      FfiKvPair             = KiboKmsRestFfi::FfiKvPair
+      FfiPosturePolicy      = KiboKmsRestFfi::FfiPosturePolicy
+      FfiAllowedOracleModes = KiboKmsRestFfi::FfiAllowedOracleModes
+      FfiPosture            = KiboKmsRestFfi::FfiPosture
+      FfiStrategy           = KiboKmsRestFfi::FfiStrategy
+      FfiOracleMode         = KiboKmsRestFfi::FfiOracleMode
+      FfiAttestationTier    = KiboKmsRestFfi::FfiAttestationTier
+      FfiMinPosture         = KiboKmsRestFfi::FfiMinPosture
+      KmsProvider           = KiboKmsRestFfi::KmsProvider
+
+      # uniffi-ruby's error variants are +< StandardError+ namespaced under the
+      # +ZkFfiUniffiError+ module but do NOT +include+ it, so +rescue+-ing the
+      # module misses them — rescue the concrete variant classes instead.
+      FFI_ERRORS = [
+        KiboKmsRestFfi::ZkFfiUniffiError::Platform,
+        KiboKmsRestFfi::ZkFfiUniffiError::UpstreamKms,
+        KiboKmsRestFfi::ZkFfiUniffiError::PostureViolation
+      ].freeze
+    end
+
+    # Encrypt +input.plaintext+ via the customer KMS, client-side. Returns the
+    # opaque ZKFE envelope (+EncryptOutput+). Raises +K9o::KError+ on failure.
+    def self.encrypt(input)
+      ensure_native!
+      begin
+        KiboKmsRestFfi.zk_encrypt_blocking(input)
+      rescue *FFI_ERRORS => e
+        raise to_kerror(e)
+      end
+    end
+
+    # Decrypt a ZKFE +input.envelope+. +strategy+, +attestation_tier+, and
+    # +encryption_context+ MUST match the encrypt-time values (AAD-bound).
+    def self.decrypt(input)
+      ensure_native!
+      begin
+        KiboKmsRestFfi.zk_decrypt_blocking(input)
+      rescue *FFI_ERRORS => e
+        raise to_kerror(e)
+      end
+    end
+
+    # Guard: raise a clear KError if the native lib is absent (evaluated BEFORE
+    # any reference to the +KiboKmsRestFfi+ namespace, which may be undefined).
+    def self.ensure_native!
+      return if NATIVE_AVAILABLE
+
+      raise K9o::KError.new(
+        code: 'KIBO_NATIVE_UNAVAILABLE',
+        message: 'kibo ZK native library not available for this platform/Ruby; install the platform-specific k9o gem.'
+      )
+    end
+    private_class_method :ensure_native!
+
+    # Map the bound core's uniffi error -> +K9o::KError+, codes passed through.
+    def self.to_kerror(e)
+      case e
+      when KiboKmsRestFfi::ZkFfiUniffiError::PostureViolation
+        K9o::KError.new(
+          code: e.code, message: e.message,
+          context: { dimension: e.dimension, requested: e.requested, declared: e.declared }
+        )
+      when KiboKmsRestFfi::ZkFfiUniffiError::Platform
+        K9o::KError.new(code: e.code, message: e.message)
+      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)
+      else
+        K9o::KError.new(code: 'KIBO_FFI_ERROR', message: e.message)
+      end
+    end
+    private_class_method :to_kerror
+  end
+end

data/lib/k9o/me.rb

@@ -0,0 +1,160 @@
+# 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.
+  class Me
+    attr_reader :profile, :sessions, :api_tokens, :notifications, :audit_log, :data_export
+
+    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
+      def initialize(config)
+        @config = config
+      end
+
+      def get
+        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 })
+      end
+    end
+
+    # k9o.me.sessions.*
+    class Sessions
+      def initialize(config)
+        @config = config
+      end
+
+      def list
+        HttpTransport.request(config: @config, method: 'GET', path: UrlGrammar.org_path('me/sessions'))
+      end
+
+      def revoke(session_id)
+        HttpTransport.request(config: @config, method: 'DELETE',
+                              path: UrlGrammar.org_path("me/sessions/#{enc(session_id)}"))
+      end
+
+      def revoke_all
+        HttpTransport.request(config: @config, method: 'DELETE', path: UrlGrammar.org_path('me/sessions'))
+      end
+
+      private
+
+      def enc(s)
+        ::URI.encode_www_form_component(s)
+      end
+    end
+
+    # k9o.me.api_tokens.*
+    class ApiTokens
+      def initialize(config)
+        @config = config
+      end
+
+      def list
+        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
+        HttpTransport.request(config: @config, method: 'POST', path: UrlGrammar.org_path('me/api-tokens'), body: body)
+      end
+
+      def delete(token_id)
+        HttpTransport.request(config: @config, method: 'DELETE',
+                              path: UrlGrammar.org_path("me/api-tokens/#{enc(token_id)}"))
+      end
+
+      private
+
+      def enc(s)
+        ::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