k9o 1.1.0

data/lib/k9o/url_grammar.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module K9o
+  # URL grammar helpers.
+  module UrlGrammar
+    SLUG_RE = /\A[a-z][a-z0-9-]{1,62}\z/
+
+    # Bare platform apex hosts org-subdomain derivation applies to —
+    # production and staging share the <org_slug>.<apex> wire-routing
+    # scheme (confirmed live). A third apex needs the same confirmation
+    # before joining this set.
+    ORG_DERIVABLE_APEXES = %w[api.k9o.io api-staging.k9o.io].freeze
+
+    module_function
+
+    def validate_base_url(base_url)
+      raise KError.new(
+        code: 'K9O_INVALID_BASE_URL',
+        message: "base_url #{base_url.inspect} is not a valid URL",
+        context: { base_url: base_url }
+      ) unless base_url.is_a?(String) && !base_url.empty?
+
+      begin
+        uri = URI.parse(base_url)
+      rescue URI::InvalidURIError => e
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} is not a valid URL: #{e.message}",
+          context: { base_url: base_url }
+        )
+      end
+
+      unless %w[http https].include?(uri.scheme)
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} uses unsupported scheme #{uri.scheme.inspect}; expected http or https",
+          context: { base_url: base_url, scheme: uri.scheme }
+        )
+      end
+      if uri.host.nil? || uri.host.empty?
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} missing host",
+          context: { base_url: base_url }
+        )
+      end
+      if uri.path && uri.path != '' && uri.path != '/'
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} must not contain a path segment; got #{uri.path.inspect}",
+          context: { base_url: base_url, path: uri.path }
+        )
+      end
+      if uri.query || uri.fragment
+        raise KError.new(
+          code: 'K9O_INVALID_BASE_URL',
+          message: "base_url #{base_url.inspect} must not contain query or fragment",
+          context: { base_url: base_url }
+        )
+      end
+
+      host_port = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+      "#{uri.scheme}://#{host_port}"
+    end
+
+    # Resolve the effective base_url. base_url is
+    # OPTIONAL — it defaults to the platform apex https://api.k9o.io. When the
+    # (validated) host is a bare apex in ORG_DERIVABLE_APEXES and org_slug is
+    # supplied, the SDK composes the canonical org-subdomain wire root
+    # https://<org_slug>.<apex>. An explicit <org_slug> subdomain,
+    # a self-hosted / Sovereign host, or a dev host (anything not in that
+    # set) passes through unchanged — org_slug is intentionally NOT composed
+    # onto a non-apex host.
+    #
+    # Fixed 2026-08-30 (SDK-2): this used to silently ignore org_slug for
+    # api-staging.k9o.io too, not just genuine self-hosted/custom hosts,
+    # since only the literal production apex string was checked.
+    def resolve_base_url(base_url, org_slug = nil)
+      validated = validate_base_url(base_url.nil? ? 'https://api.k9o.io' : base_url)
+      uri = URI.parse(validated)
+      if ORG_DERIVABLE_APEXES.include?(uri.host) && org_slug
+        validate_slug(org_slug, 'org')
+        return "#{uri.scheme}://#{org_slug}.#{uri.host}"
+      end
+      validated
+    end
+
+    def validate_slug(slug, kind)
+      unless slug.is_a?(String) && slug.match?(SLUG_RE) && !slug.end_with?('-')
+        raise KError.new(
+          code: 'K9O_INVALID_FIELD_VALUE',
+          message: "#{kind}_slug #{slug.inspect} does not match required format ^[a-z][a-z0-9-]{1,62}$ (must not end with hyphen)",
+          context: { slug: slug, kind: kind }
+        )
+      end
+    end
+
+    def project_path(project_slug, sub_resource)
+      cleaned = sub_resource.sub(%r{\A/}, '')
+      "/@#{project_slug}/#{cleaned}"
+    end
+
+    def org_path(resource)
+      "/#{resource.sub(%r{\A/}, '')}"
+    end
+
+    def platform_path(resource)
+      "/#{resource.sub(%r{\A/}, '')}"
+    end
+  end
+end

data/lib/k9o/vault.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'uri'
+
+module K9o
+  # `k9o.kibo.vault.secrets.*` — the typed secrets surface
+  # (`services/gateway/src/routes/vault-secrets.ts`). Full family: list / get /
+  # create / reveal_challenge / reveal / update / rotate / move / delete.
+  #
+  # Contract live-verified against the real staging gateway (not just the
+  # route's OpenAPI schema, which is wrong/incomplete in several places noted
+  # below) by the `@k9o/kibo` TS reference build — this wrapper mirrors that
+  # verified behavior exactly:
+  #
+  #   - Every operation on a NAMED secret (everything except `list`) REQUIRES
+  #     `region` on the query string. Omitting it fails with
+  #     K9O_INVALID_FIELD_VALUE ("this request requires an authoritative
+  #     region"). NOT documented in the route's OpenAPI schema. `list` is the
+  #     one exception (verified it does NOT need `region`).
+  #   - The wire `value` field is base64 in BOTH directions, contradicting the
+  #     OpenAPI's plain-language "the plaintext to seal" description (reads
+  #     like it should be raw). A raw non-base64 `value` on create/update is
+  #     rejected as unparseable. `create`/`update` take plaintext as a normal
+  #     Ruby String and base64-encode it here; `reveal` base64-decodes the
+  #     wire `value` back to plaintext before returning it — callers never
+  #     see base64 on either side.
+  #   - `update`/`rotate`/`move` responses are LIVE-VERIFIED NARROWER than (or
+  #     entirely undocumented vs.) the OpenAPI's claimed `SecretSummary` — see
+  #     the comment on each method below.
+  #
+  # `data` is returned as the raw wire Hash (camelCase string keys), matching
+  # this package's existing convention (Projects/Policies/Studio/etc. all
+  # return `envelope.data` untransformed — there is no generic
+  # camelCase<->snake_case response transform anywhere in this gem); `reveal`
+  # is the one exception, where the `value` key is base64-decoded in place
+  # (mirroring the TS reference's own `value`-only transform).
+  class VaultSecrets
+    def initialize(config)
+      @config = config
+    end
+
+    # List secrets (metadata only — never lists ciphertext).
+    # `GET /@<project_slug>/vault/secrets`.
+    # The one secrets operation that does NOT need `region` (live-verified).
+    def list(prefix: nil, cursor: nil, limit: nil)
+      slug = require_project_slug
+      q = {}
+      q['prefix'] = prefix if prefix
+      q['cursor'] = cursor if cursor
+      q['limit'] = limit if limit
+      HttpTransport.request(
+        config: @config, method: 'GET',
+        path: UrlGrammar.project_path(slug, 'vault/secrets'),
+        query: q
+      )
+    end
+
+    # Read a secret's metadata (never its value — use `reveal_challenge` +
+    # `reveal` for that).
+    # `GET /@<project_slug>/vault/secrets/<name>?region=<region>`.
+    #
+    # KNOWN LIVE BUG (staging, 2026-09-05): this call currently fails with
+    # K9O_REVEAL_CHALLENGE_REQUIRED on every attempt — the gateway does not
+    # honor its own documented "no X-K9O-Reveal-Challenge header => return
+    # metadata" behavior; it demands a challenge unconditionally. Implemented
+    # per the documented contract anyway (this is a backend defect to flag,
+    # not something to design around) — `list(prefix: exact_name)` is the
+    # current working alternative for a single secret's metadata until the
+    # gateway side is fixed.
+    def get(name, region:)
+      slug = require_project_slug
+      HttpTransport.request(
+        config: @config, method: 'GET',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'region' => region }
+      )
+    end
+
+    # Create a secret under the caller's own auth.
+    # `POST /@<project_slug>/vault/secrets/<name>?region=<region>` → the full
+    # `sec_<base62>` summary.
+    #
+    # `region` scopes the vault WRITE itself (residency guard) and is
+    # REQUIRED — live-verified against staging, not documented in the route's
+    # OpenAPI schema.
+    #
+    # `visibility` (`{'kind' => 'private'}` or
+    # `{'kind' => 'shared', 'principals' => [...], 'roles' => [...]}`) and
+    # `metadata` (`Hash[String, String]`) are passed through verbatim — their
+    # own field names are already single words, so no wire-casing applies.
+    def create(name:, value:, region:, visibility: nil, metadata: nil)
+      slug = require_project_slug
+      body = { 'value' => Base64.strict_encode64(value) }
+      body['visibility'] = visibility if visibility
+      body['metadata'] = metadata if metadata
+      HttpTransport.request(
+        config: @config, method: 'POST',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'region' => region },
+        body: body
+      )
+    end
+
+    # Mint a single-use reveal challenge — present it as
+    # `X-K9O-Reveal-Challenge` on the immediately-following `reveal` call.
+    # `POST .../<name>?op=reveal-challenge&region=<region>`.
+    def reveal_challenge(name, region:)
+      slug = require_project_slug
+      HttpTransport.request(
+        config: @config, method: 'POST',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'op' => 'reveal-challenge', 'region' => region }
+      )
+    end
+
+    # Reveal a secret's plaintext value using a single-use challenge from
+    # `reveal_challenge`. `GET .../<name>?region=<region>` with
+    # `X-K9O-Reveal-Challenge`. Base64-decodes the wire's `value` back to
+    # plaintext (live-verified: the reveal response's `value` is base64,
+    # symmetric with `create`'s encode) before returning it to the caller.
+    def reveal(name, region:, challenge:)
+      slug = require_project_slug
+      envelope = HttpTransport.request(
+        config: @config, method: 'GET',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'region' => region },
+        headers: { 'X-K9O-Reveal-Challenge' => challenge }
+      )
+      data = envelope.data
+      if data.is_a?(Hash) && data.key?('value')
+        data = data.merge('value' => Base64.decode64(data['value']))
+      end
+      Envelope.new(data: data, meta: envelope.meta)
+    end
+
+    # Update a secret's value (bumps version) — owner-only.
+    # `PUT .../<name>?region=<region>`.
+    #
+    # LIVE-VERIFIED NARROWER than documented: the gateway returns only
+    # `{id, name, version}` on a real PUT, not the full summary the OpenAPI
+    # schema claims — call `get` afterward if the full summary is needed.
+    def update(name, region:, value:, metadata: nil)
+      slug = require_project_slug
+      body = { 'value' => Base64.strict_encode64(value) }
+      body['metadata'] = metadata if metadata
+      HttpTransport.request(
+        config: @config, method: 'PUT',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'region' => region },
+        body: body
+      )
+    end
+
+    # Rotate a secret's wrapping key (re-wraps under a fresh `kid`; content
+    # unchanged) — owner-only. `POST .../<name>?op=rotate&region=<region>`.
+    #
+    # LIVE-VERIFIED undocumented shape: `{id, name, version, rotatedAt,
+    # ledgerSequenceNumber}` — the route's OpenAPI schema doesn't document
+    # this response at all.
+    def rotate(name, region:)
+      slug = require_project_slug
+      HttpTransport.request(
+        config: @config, method: 'POST',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'op' => 'rotate', 'region' => region }
+      )
+    end
+
+    # Move (rename) a secret's hierarchical path — owner-only.
+    # `POST .../<name>?op=move&region=<region>` with `{newPath}`.
+    #
+    # LIVE-VERIFIED undocumented shape: `{id, name, event}` (observed
+    # `event: "SECRET_PATH_CHANGED"`; treat as a plain String, not a closed
+    # enum — only one sample was observed).
+    def move(name, region:, new_path:)
+      slug = require_project_slug
+      HttpTransport.request(
+        config: @config, method: 'POST',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'op' => 'move', 'region' => region },
+        body: { 'newPath' => new_path }
+      )
+    end
+
+    # Retire a secret — owner-only. `DELETE .../<name>?region=<region>` →
+    # `204 No Content` (HttpTransport already maps that to `data: nil`).
+    def delete(name, region:)
+      slug = require_project_slug
+      HttpTransport.request(
+        config: @config, method: 'DELETE',
+        path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
+        query: { 'region' => region }
+      )
+    end
+
+    private
+
+    def require_project_slug
+      Studio.require_project_slug(@config, 'kibo.vault.secrets')
+    end
+
+    def enc(s)
+      ::URI.encode_www_form_component(s)
+    end
+  end
+
+  # `k9o.kibo.vault.*` — the Kibo vault surface (member-plane, project-scoped).
+  # Currently just `secrets`; a `zk_deks` accessor
+  # (F.5, `POST vault/zk-deks` / `GET vault/zk-deks/<id>`) would
+  # nest here alongside it if/when that surface is built for Ruby — out of
+  # scope for this wrapper, which only covers the vault-secrets audit gap.
+  class KiboVault
+    attr_reader :secrets
+
+    def initialize(config)
+      @secrets = VaultSecrets.new(config)
+    end
+  end
+
+  # `k9o.kibo.*` — per-client namespace root for the Kibo vault REST surface.
+  # Distinct from the module-level `K9o::Kibo` (native ZK `encrypt`/`decrypt`
+  # FFI bindings, /, called directly as
+  # `K9o::Kibo.encrypt`/`.decrypt` since that surface needs no per-client HTTP
+  # config): this class exists so `client.kibo.vault.secrets.*` is reachable
+  # per client instance, mirroring the TS reference's
+  # `client.kibo.vault.{zk_deks, secrets}` shape.
+  class KiboNamespace
+    attr_reader :vault
+
+    def initialize(config)
+      @vault = KiboVault.new(config)
+    end
+  end
+end

data/lib/k9o/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module K9o
+  VERSION = '1.1.0'
+end

data/lib/k9o.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# k9o — Kilimanjaro platform SDK for Ruby.
+# Idiomatic: snake_case methods + raise K9o::KError +
+# Net::HTTP transport.
+#
+#   k9o = K9o.create_client(
+#     base_url: "https://acme.api.k9o.io",
+#     api_key: ENV["K9O_API_KEY"],
+#     org_slug: "acme",
+#     project_slug: "member-portal",
+#   )
+#
+#   begin
+#     response = k9o.from("posts").select.limit(10).execute
+#     response.data.each { |row| puts row }
+#
+#     session = k9o.gate.sign_in(email: "u@x.com", password: "...")
+#     puts "signed in: #{session.data['user']['id']}"
+#   rescue K9o::KError => e
+#     warn "[#{e.code}] #{e.message}: #{e.recommendation}"
+#     raise
+#   end
+
+require_relative 'k9o/version'
+require_relative 'k9o/kerror'
+require_relative 'k9o/envelope'
+require_relative 'k9o/url_grammar'
+require_relative 'k9o/region'
+require_relative 'k9o/http_transport'
+require_relative 'k9o/data'
+require_relative 'k9o/projects'
+require_relative 'k9o/gate'
+require_relative 'k9o/studio'
+require_relative 'k9o/compute'
+require_relative 'k9o/ai'
+require_relative 'k9o/storage'
+require_relative 'k9o/realtime'
+require_relative 'k9o/migrations'
+require_relative 'k9o/functions'
+require_relative 'k9o/policies'
+require_relative 'k9o/audit'
+require_relative 'k9o/orgs'
+require_relative 'k9o/me'
+require_relative 'k9o/org'
+# kibo ZK BYOK/HYOK crypto — self-guards its native binding (LoadError-safe), so
+# requiring k9o never breaks on a platform without the kibo native lib.
+require_relative 'k9o/kibo'
+# kibo vault REST surface (client.kibo.vault.secrets) —.
+require_relative 'k9o/vault'
+# Barbican guardrail SDK — self-guards its native binding (LoadError-safe), so
+# requiring k9o never breaks on a platform without the barbican native lib.
+require_relative 'k9o/barbican'
+require_relative 'k9o/client'

data/sig/k9o/ai.rbs

@@ -0,0 +1,16 @@
+# RBS signatures for the `client.ai` namespace (platform AI primitives).
+
+module K9o
+  class Ai
+    # `input` is one string or an array of strings, sent exactly as given.
+    # `model` is omitted from the request body when nil (server default).
+    # Returns an Envelope whose `data` is
+    # { "embeddings" => Array[Array[Float]], "model" => String, "dimensions" => Integer }.
+    def initialize: (untyped config) -> void
+    def embed: (input: (String | Array[String]), ?model: String?) -> Envelope
+  end
+
+  class K9oClient
+    attr_reader ai: Ai
+  end
+end

data/sig/k9o/gate.rbs

@@ -0,0 +1,11 @@
+# RBS signatures for the `client.gate` namespace (additions).
+
+module K9o
+  class Gate
+    # GET /@<slug>/gate/hosted. Unauthenticated (no credential sent).
+    # Returns an Envelope whose `data` is { "signInUrl" => String, "rpId" => String }.
+    # Raises KError (K9O_MISSING_PROJECT_CONTEXT) without a project slug; the
+    # uniform 404 K9O_PROJECT_NOT_FOUND for unknown org / deleted / non-Gate project.
+    def hosted: () -> Envelope
+  end
+end

data/sig/k9o/migrations.rbs

@@ -0,0 +1,138 @@
+# RBS signatures for the migration control-plane type model (ch13 §2.2, Ruby
+# TIER-3: documented + statically-checkable hash pass-through). These describe
+# the FIXED control-plane Operation union + its sub-shapes so steep/typeprof
+# can check migration authoring. The runtime carries plain Hashes; the wire
+# JSON matches packages/core/src/migrations.ts (snake_case keys, `searchable`
+# NESTED inside the `encrypted` object form).
+#
+# Closed-union note: RBS cannot express "exactly one key set", so the Operation
+# variants are typed as distinct single-key hash shapes and the closed-union
+# property is enforced at wire + server validation (true for every tier).
+
+module K9o
+  # The `encrypted` union: the bare `true` shorthand, or the object form with a
+  # NESTED `searchable` flag.
+  type column_encryption = { store: ("inline" | "vault"), ?searchable: bool }
+  type encrypted = (true | column_encryption)
+
+  type fk_action = ("CASCADE" | "RESTRICT" | "SET NULL" | "NO ACTION")
+
+  type column_references = {
+    collection: String,
+    on: String,
+    ?on_delete: fk_action,
+    ?on_update: fk_action,
+  }
+
+  # `type` stays a String (parser-owned vocabulary; not an enum).
+  type column_spec = {
+    name: String,
+    type: String,
+    ?primary_key: bool,
+    ?not_null: bool,
+    ?unique: bool,
+    ?default: String,
+    ?references: column_references,
+    ?encrypted: encrypted,
+    ?blind_indexed: bool,
+  }
+
+  type index_spec = {
+    ?name: String,
+    columns: Array[String],
+    ?unique: bool,
+  }
+
+  # KEY-TAGGED Operation union — EXACTLY these 6 (FROZEN at v2; rename_column is
+  # the pending 7th, intentionally absent). Each variant is a single-key hash.
+  type create_table_op = { create_table: { name: String, columns: Array[column_spec], ?indexes: Array[index_spec] } }
+  type drop_table_op   = { drop_table: String }
+  type add_column_op   = { add_column: { table: String, column: column_spec } }
+  type drop_column_op  = { drop_column: { table: String, column: String } }
+  type alter_table_op  = { alter_table: { name: String, ?add_columns: Array[column_spec], ?drop_columns: Array[String] } }
+  type create_index_op = { create_index: { table: String, index: index_spec } }
+  type drop_index_op   = { drop_index: { name: String } }
+
+  type operation = (create_table_op | drop_table_op | add_column_op | drop_column_op | alter_table_op | create_index_op | drop_index_op)
+
+  type action_rule = { ?rule: untyped }
+
+  type relationship_spec = {
+    collection: String,
+    on: String,
+    as: String,
+    ?type: ("inner" | "left"),
+  }
+
+  type collection_policy = {
+    ?references: Array[relationship_spec],
+    ?actions: { ?select: action_rule, ?insert: action_rule, ?update: action_rule, ?delete: action_rule },
+  }
+
+  type storage_bucket_policy = {
+    ?public: bool,
+    ?actions: { ?read: action_rule, ?upload: action_rule, ?delete: action_rule, ?list: action_rule },
+  }
+
+  type migration_policy = {
+    ?collections: Hash[String, collection_policy],
+    ?storage: { ?buckets: Hash[String, storage_bucket_policy] },
+  }
+
+  type migration = {
+    version: Integer,
+    slug: String,
+    up: Array[operation],
+    down: Array[operation],
+    ?policy: migration_policy,
+  }
+
+  type applied_migration = {
+    version: Integer,
+    slug: String,
+    checksum: String,
+    appliedAt: String,
+  }
+
+  type pending_migration = {
+    pendingId: String,
+    version: Integer,
+    slug: String,
+    checksum: String,
+    submittedAt: String,
+    submittedBy: String,
+  }
+
+  class Migrations
+    @config: untyped
+    def initialize: (untyped config) -> void
+    def apply: (Array[migration] migrations) -> untyped
+    def list: () -> untyped
+    def get: (untyped version) -> untyped
+    def queue: (Array[migration] migrations) -> untyped
+    def list_pending: () -> untyped
+    def apply_pending: (String pending_id) -> untyped
+    def reject_pending: (String pending_id, ?reason: String?) -> untyped
+    def delete_pending: (String pending_id) -> untyped
+
+    private
+    def require_project_slug: () -> String
+    def enc: (untyped s) -> String
+
+    # Typed keyword-arg constructors for the control-plane Operation union.
+    module Build
+      def self?.column: (name: String, type: String, ?primary_key: bool?, ?not_null: bool?, ?unique: bool?, ?default: String?, ?references: column_references?, ?encrypted: encrypted?, ?blind_indexed: bool?) -> column_spec
+      def self?.column_encryption: (store: ("inline" | "vault"), ?searchable: bool?) -> column_encryption
+      def self?.references: (collection: String, on: String, ?on_delete: fk_action?, ?on_update: fk_action?) -> column_references
+      def self?.index: (columns: Array[String], ?name: String?, ?unique: bool?) -> index_spec
+      def self?.create_table: (name: String, columns: Array[column_spec], ?indexes: Array[index_spec]?) -> create_table_op
+      def self?.drop_table: (String name) -> drop_table_op
+      def self?.add_column: (table: String, column: column_spec) -> add_column_op
+      def self?.drop_column: (table: String, column: String) -> drop_column_op
+      def self?.alter_table: (name: String, ?add_columns: Array[column_spec]?, ?drop_columns: Array[String]?) -> alter_table_op
+      def self?.create_index: (table: String, index: index_spec) -> create_index_op
+      def self?.drop_index: (name: String) -> drop_index_op
+      def self?.migration: (version: Integer, slug: String, up: Array[operation], down: Array[operation], ?policy: migration_policy?) -> migration
+    end
+  end
+end

data/sig/k9o/region.rbs

@@ -0,0 +1,19 @@
+# RBS signatures for regional host resolution (K9o::Region).
+
+module K9o
+  module Region
+    REGION_FREE_ORG_HOST: Regexp
+    REGION_CODE: Regexp
+
+    # The regional origin `location` may name for `host`, or nil.
+    def self.origin_from_location: (String host, String location, String base) -> String?
+    # The origin requests go to: cached regional origin, else the configured base URL. Never raises.
+    def self.resolve_origin: (HttpClientConfig config) -> String
+    def self.probe: (HttpClientConfig config) -> [String, bool]
+  end
+
+  class HttpClientConfig
+    attr_reader region_mutex: Thread::Mutex
+    attr_accessor regional_origin: String?
+  end
+end

data/sig/k9o/storage.rbs

@@ -0,0 +1,41 @@
+# RBS signatures for the `client.storage` namespace (buckets and objects).
+
+module K9o
+  module Multipart
+    type part = { name: String, value: untyped, ?filename: String, ?content_type: String }
+    def self.encode: (Array[part] parts) -> [String, String]
+  end
+
+  class Storage
+    MAX_EXPIRES_IN: Integer
+
+    def initialize: (untyped config) -> void
+    def list_buckets: () -> Envelope
+    def get_bucket: (String name) -> Envelope
+    def create_bucket: (String name, ?public: bool?, ?file_size_limit: Integer?, ?allowed_mime_types: Array[String]?,
+                        ?versioning: bool?, ?delete_after_days: Integer?, ?byos_binding_id: String?) -> Envelope
+    # `patch` keys: snake_case or wire camelCase; an explicit nil clears a limit.
+    def update_bucket: (String name, Hash[(String | Symbol), untyped] patch) -> Envelope
+    def delete_bucket: (String name, ?empty: bool) -> Envelope
+    def from: (String bucket) -> BucketHandle
+
+    class BucketHandle
+      def initialize: (untyped config, String bucket) -> void
+      # `data` is a String (sent as its bytes) or an IO-like responding to #read.
+      def upload: (String path, (String | _Reader) data, ?content_type: String?, ?upsert: bool,
+                   ?metadata: Hash[String, String]?) -> Envelope
+      # `expires_in` is required: Integer 1..604800 (K9O_INVALID_FIELD_VALUE otherwise).
+      def create_signed_url: (String path, expires_in: Integer, ?download: bool?) -> Envelope
+      def list: (?prefix: String?) -> Envelope
+      def remove: (String path) -> Envelope
+    end
+
+    interface _Reader
+      def read: () -> String
+    end
+  end
+
+  class K9oClient
+    attr_reader storage: Storage
+  end
+end