k9o 1.2.0 → 1.3.0

data/lib/k9o/realtime.rb

@@ -1,54 +1,32 @@
 # frozen_string_literal: true
 
 module K9o
-  # Realtime Subscriptions namespace (ALL-LIVE primitive).
+  # Realtime Subscriptions namespace.
   #
-  # Ruby idiom: #subscribe returns an Enumerator iterated via
-  # `.each`. Per + the SDK-abstracted-primitive discipline the
-  # SDK picks the transport; SPLIT (polling) is the internal fallback. The
-  # Net::HTTP-based Ruby SDK uses SSE primary (no stdlib WebSocket);
-  # #subscribe_poll exposes the poll fallback. #replay is one-shot catch-up.
+  # Transport: SSE over GET /@<slug>/realtime/subscribe. The gateway serves no WebSocket upgrade and no durable
+  # replay, so neither is offered; after an `event: resync` frame the caller re-reads current state from the data
+  # plane and resubscribes. #subscribe returns an Enumerator iterated via `.each`.
   class Realtime
     def initialize(config)
       @config = config
     end
 
-    # Subscribe via SSE transport (primary); returns an
-    # Enumerator yielding event hashes.
+    # Subscribe via SSE; returns an Enumerator yielding event hashes
+    # { 'topic', 'eventType', 'payload', 'occurredAt' } (the gateway's spelling). Control frames such as `resync`
+    # carry no +eventType+ and are skipped.
     def subscribe(topic, filter: nil)
       slug = Studio.require_project_slug(@config, 'realtime')
       q = { 'topic' => topic }
       q['filter'] = JSON.dump(filter) if filter
-      HttpTransport.stream_sse(config: @config, method: 'GET',
-                               path: UrlGrammar.project_path(slug, 'realtime/subscribe'), query: q)
-    end
-
-    # One-shot historical replay (capped 10k server-side).
-    def replay(topic, from_sequence:, filter: nil, until_sequence: nil, limit: nil)
-      slug = Studio.require_project_slug(@config, 'realtime')
-      unless from_sequence.is_a?(Integer) && from_sequence >= 0
-        raise KError.new(
-          code: 'K9O_INVALID_FILTER',
-          message: 'replay from_sequence must be a non-negative integer',
-          context: { fromSequence: from_sequence },
-          recommendation: 'Pass the highest sequence number you have already observed (or 0 to replay from the start).'
-        )
+      frames = HttpTransport.stream_sse(config: @config, method: 'GET',
+                                        path: UrlGrammar.project_path(slug, 'realtime/subscribe'), query: q)
+      Enumerator.new do |yielder|
+        frames.each do |event|
+          yielder << event if event.is_a?(Hash) && event['eventType'].is_a?(String)
+        end
       end
-      body = { 'topic' => topic, 'fromSequence' => from_sequence }
-      body['filter'] = filter if filter
-      body['untilSequence'] = until_sequence if until_sequence
-      body['limit'] = limit if limit
-      HttpTransport.request(config: @config, method: 'POST',
-                            path: UrlGrammar.project_path(slug, 'realtime/replay'), body: body)
-    end
-
-    # Poll-transport fallback (SDK-internal SPLIT). Single batch
-    # via replay endpoint; caller loops tracking highest observed sequence.
-    def subscribe_poll(topic, from_sequence:, filter: nil)
-      replay(topic, from_sequence: from_sequence, filter: filter)
     end
 
-    # Typed builders for the 6 closed topic families.
     module Topic
       module_function
 

data/lib/k9o/region.rb

@@ -6,30 +6,32 @@ require 'uri'
 module K9o
   # Regional host resolution.
   #
-  # The region-free org host `<org>.api[-staging].k9o.io` redirects GET/HEAD
-  # only and REFUSES a request carrying a body / Authorization / cookie, so
-  # credentials must go to `<org>.api[-staging]-<rgn>.k9o.io`. The SDK learns
-  # the region with ONE unauthenticated `HEAD https://<org>.api[-staging].k9o.io/`
-  # (Net::HTTP never follows redirects, so the 308 is read, not followed),
+  # A region-free org host `<org>.api.<rest>` (or `<org>.api-staging.<rest>`)
+  # redirects GET/HEAD only and REFUSES a request carrying a body /
+  # Authorization / cookie, so credentials must go to `<org>.api-<rgn>.<rest>`.
+  # The SDK learns the region with ONE unauthenticated HEAD to the configured
+  # host (Net::HTTP never follows redirects, so the 308 is read, not followed),
   # takes the 308 `Location`, and caches the regional origin per client config.
   #
-  # - Only a region-free org host is ever probed; any other base URL is used
-  #   exactly as given.
+  # Nothing here knows an apex: the host comes from the configured base URL and
+  # `<rest>` is whatever follows the gateway label, so public-cloud,
+  # internal-apex, air-gapped and localhost deployments all work.
+  #
+  # - Only a region-free org host (see UrlGrammar.parse_api_host) is ever
+  #   probed; any other base URL is used exactly as given.
   # - The probe carries no Authorization, cookie or default header.
   # - The Location is trusted only if https, no userinfo, no port, and host is
-  #   exactly `<same org>.<same apex family>-<rgn>.k9o.io` (rgn = [a-z]{2}\d{2}).
+  #   exactly the same org and the same remainder with a region code
+  #   ([a-z]{2}\d{2}) appended to the gateway label.
   # - Any other status or failure keeps the configured base URL. A definite
   #   answer is cached; a network failure of the probe is not.
   module Region
-    REGION_FREE_ORG_HOST = /\A([a-z][a-z0-9-]{1,62})\.(api|api-staging)\.k9o\.io\z/.freeze
-    REGION_CODE = /\A[a-z]{2}\d{2}\z/.freeze
-
     module_function
 
     # The regional origin `location` may name for `host`, or nil. Pure.
     def origin_from_location(host, location, base)
-      m = REGION_FREE_ORG_HOST.match(host)
-      return nil if m.nil?
+      from = UrlGrammar.parse_api_host(host)
+      return nil if from.nil? || from.org_slug.nil? || !from.region.nil?
 
       begin
         u = URI.join(base.sub(%r{/+\z}, '') + '/', location)
@@ -40,11 +42,10 @@ module K9o
       return nil unless u.userinfo.nil? && u.user.nil? && u.password.nil?
       return nil unless u.port == u.default_port
 
-      org = Regexp.escape(m[1])
-      apex = Regexp.escape(m[2])
       h = u.host.to_s.downcase
-      r = /\A#{org}\.#{apex}-([a-z0-9]+)\.k9o\.io\z/.match(h)
-      return nil if r.nil? || !REGION_CODE.match?(r[1])
+      to = UrlGrammar.parse_api_host(h)
+      return nil if to.nil? || to.region.nil?
+      return nil unless to.org_slug == from.org_slug && to.family == from.family && to.apex == from.apex
 
       "https://#{h}"
     end
@@ -70,7 +71,8 @@ module K9o
       rescue URI::Error
         return [configured, true]
       end
-      return [configured, true] unless REGION_FREE_ORG_HOST.match?(host)
+      parsed_host = UrlGrammar.parse_api_host(host)
+      return [configured, true] if parsed_host.nil? || parsed_host.org_slug.nil? || !parsed_host.region.nil?
 
       begin
         probe_uri = URI.parse("#{configured.sub(%r{/+\z}, '')}/")

data/lib/k9o/studio.rb

@@ -25,7 +25,7 @@ module K9o
       slug
     end
 
-    # k9o.studio.workflows.*.
+    # k9o.studio.workflows.*
     class Workflows
       attr_reader :runs
 
@@ -34,17 +34,19 @@ module K9o
         @runs = Runs.new(config)
       end
 
-      def list(status: nil, trigger_type: nil, limit: nil, cursor: nil)
+      # GET /@<slug>/workflows — the route filters by +status+ and pages with +limit+ / +cursor+.
+      def list(status: nil, limit: nil, cursor: nil)
         slug = Studio.require_project_slug(@config, 'studio.workflows')
         q = {}
         q['status'] = status if status
-        q['triggerType'] = trigger_type if trigger_type
         q['limit'] = limit if limit
         q['cursor'] = cursor if cursor
         HttpTransport.request(config: @config, method: 'GET',
                               path: UrlGrammar.project_path(slug, 'workflows'), query: q)
       end
 
+      # POST /@<slug>/workflows. +workflow+ is the gateway's body: 'name', 'triggerType', 'triggerConfig',
+      # 'actions' (each { 'index', 'action_type', 'config', ... }), optional 'description', 'status', 'rbacBinding'.
       def create(workflow)
         slug = Studio.require_project_slug(@config, 'studio.workflows')
         HttpTransport.request(config: @config, method: 'POST',
@@ -69,12 +71,12 @@ module K9o
                               path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}"))
       end
 
-      # Manual-trigger a run (trigger_type=manual only).
+      # Manual-trigger a run (manual workflows only): POST /@<slug>/workflows/<id>/runs { triggerContext }.
       def trigger(workflow_id, trigger_context = {})
         slug = Studio.require_project_slug(@config, 'studio.workflows')
         HttpTransport.request(config: @config, method: 'POST',
                               path: UrlGrammar.project_path(slug, "workflows/#{encode(workflow_id)}/runs"),
-                              body: trigger_context)
+                              body: { 'triggerContext' => trigger_context })
       end
 
       private
@@ -83,15 +85,18 @@ module K9o
         ::URI.encode_www_form_component(s)
       end
 
-      # k9o.studio.workflows.runs.*.
+      # k9o.studio.workflows.runs.*
       class Runs
         def initialize(config)
           @config = config
         end
 
-        def list(workflow_id, status: nil)
+        # GET /@<slug>/workflows/<id>/runs — pages with +limit+ / +cursor+ (the route has no status filter).
+        def list(workflow_id, limit: nil, cursor: nil)
           slug = Studio.require_project_slug(@config, 'studio.workflows')
-          q = status ? { 'status' => status } : nil
+          q = {}
+          q['limit'] = limit if limit
+          q['cursor'] = cursor if cursor
           HttpTransport.request(config: @config, method: 'GET',
                                 path: UrlGrammar.project_path(slug, "workflows/#{enc(workflow_id)}/runs"), query: q)
         end
@@ -116,15 +121,20 @@ module K9o
       end
     end
 
-    # k9o.studio.dashboards.*.
+    # k9o.studio.dashboards.* — widget fields on the wire are snake_case ('widget_type', 'data_source', 'config').
     class Dashboards
       def initialize(config)
         @config = config
       end
 
-      def list(status: nil)
+      # GET /@<slug>/dashboards — filters: +status+, +pinned_only+; pages with +limit+ / +cursor+.
+      def list(status: nil, pinned_only: nil, limit: nil, cursor: nil)
         slug = Studio.require_project_slug(@config, 'studio.dashboards')
-        q = status ? { 'status' => status } : nil
+        q = {}
+        q['status'] = status if status
+        q['pinnedOnly'] = pinned_only.to_s unless pinned_only.nil?
+        q['limit'] = limit if limit
+        q['cursor'] = cursor if cursor
         HttpTransport.request(config: @config, method: 'GET',
                               path: UrlGrammar.project_path(slug, 'dashboards'), query: q)
       end

data/lib/k9o/url_grammar.rb

@@ -7,11 +7,18 @@ module K9o
   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
+    # The convenience default when the caller passes no base_url. A default value only: never used to parse a host.
+    DEFAULT_BASE_URL = 'https://api.k9o.io'
+
+    # `api` or `api-staging`, optionally followed by `-<rgn>`: the label that marks a gateway host.
+    API_LABEL = /\A(api|api-staging)(?:-([a-z]{2}\d{2}))?\z/.freeze
+
+    # The structure of a gateway API host, read from the host itself.
+    #   org_slug: first label of an org host (+acme+ in +acme.api.corp.internal+); nil for a platform host.
+    #   family:   +api+ or +api-staging+.
+    #   region:   4-character region code when the host is regional (+api-de01+), else nil.
+    #   apex:     everything after the gateway label; never matched against a list.
+    ApiHost = Struct.new(:org_slug, :family, :region, :apex)
 
     module_function
 
@@ -65,24 +72,43 @@ module K9o
       "#{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.
+    # Read the org slug and region out of a gateway host without knowing its apex. The gateway label is +api+ or
+    # +api-staging+, optionally followed by +-<rgn>+; the label before it is the org slug and whatever follows it is
+    # the apex. Returns nil for any other shape (localhost, an IP, a single-label host, a host with no gateway
+    # label), which callers use exactly as given.
+    def parse_api_host(host)
+      labels = host.to_s.downcase.split('.', -1)
+      return nil if labels.empty? || labels.any?(&:empty?)
+
+      build = lambda do |gateway_label, org_slug, rest|
+        m = API_LABEL.match(gateway_label)
+        next nil if m.nil? || rest.empty?
+
+        ApiHost.new(org_slug, m[1], m[2], rest.join('.'))
+      end
+      # Org host first: <org>.<api[-rgn]>.<apex>.
+      if labels.length >= 3 && labels[0].match?(SLUG_RE) && !labels[0].end_with?('-') && API_LABEL.match?(labels[1])
+        return build.call(labels[1], labels[0], labels[2..-1])
+      end
+      # Platform host: api.<apex>.
+      return build.call(labels[0], nil, labels[1..-1]) if labels.length >= 2 && API_LABEL.match?(labels[0])
+
+      nil
+    end
+
+    # Resolve the effective base_url. base_url is OPTIONAL: omitted, it defaults to DEFAULT_BASE_URL (the public
+    # cloud, a convenience only). When the (validated) host is a platform host (+api.<apex>+ or +api-staging.<apex>+,
+    # any apex) and org_slug is supplied, the canonical org host +<org_slug>.<host>+ is composed. Any other host (an
+    # org host already, an internal or air-gapped host, localhost) passes through unchanged; org_slug is then only
+    # sent as a header.
     def resolve_base_url(base_url, org_slug = nil)
-      validated = validate_base_url(base_url.nil? ? 'https://api.k9o.io' : base_url)
+      validated = validate_base_url(base_url.nil? ? DEFAULT_BASE_URL : base_url)
       uri = URI.parse(validated)
-      if ORG_DERIVABLE_APEXES.include?(uri.host) && org_slug
+      host = parse_api_host(uri.host)
+      if !host.nil? && host.org_slug.nil? && host.region.nil? && org_slug
         validate_slug(org_slug, 'org')
-        return "#{uri.scheme}://#{org_slug}.#{uri.host}"
+        host_port = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+        return "#{uri.scheme}://#{org_slug}.#{host_port}"
       end
       validated
     end

data/lib/k9o/vault.rb

@@ -4,45 +4,33 @@ require 'base64'
 require 'uri'
 
 module K9o
-  # `k9o.kibo.vault.secrets.*` — the typed secrets surface
+  # `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.
+  #   - `region` is OPTIONAL on every named-secret operation: the gateway
+  #     ignores any caller-supplied region and uses its own. It is sent on the
+  #     query string only when the caller passes one (never by `get`, which
+  #     reads the list route).
+  #   - The wire `value` field is base64 in BOTH directions. `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 narrower than a full summary -
+  #     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).
+  # this package's existing convention; `reveal` is the one exception, where
+  # the `value` key is base64-decoded in place.
   class VaultSecrets
+    MAX_GET_PAGES = 20
+
     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 = {}
@@ -56,40 +44,42 @@ module K9o
       )
     end
 
-    # Read a secret's metadata (never its value — use `reveal_challenge` +
+    # 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 }
+    # `GET /@<project>/vault/secrets/<name>` is a reveal and always demands an
+    # `X-K9O-Reveal-Challenge` header, so metadata is read from the list route:
+    # list with the exact name as `prefix` (limit 100, following `nextCursor`
+    # for up to MAX_GET_PAGES pages) and return the secret whose `name` equals
+    # the argument. Raises `KError` `K9O_NOT_FOUND` (status 404) when none
+    # matches. `region` is accepted for symmetry and not sent.
+    def get(name, region: nil) # rubocop:disable Lint/UnusedMethodArgument
+      cursor = nil
+      MAX_GET_PAGES.times do
+        env = list(prefix: name, cursor: cursor, limit: 100)
+        data = env.data || {}
+        secret = (data['secrets'] || []).find { |s| s['name'] == name }
+        return Envelope.new(data: secret, meta: env.meta) if secret
+
+        cursor = data['nextCursor']
+        break if cursor.nil? || cursor.to_s.empty?
+      end
+      raise KError.new(
+        code: 'K9O_NOT_FOUND',
+        message: "No secret named '#{name}' in this project.",
+        context: { 'name' => name },
+        status: 404
       )
     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.
+    # `POST /@<project_slug>/vault/secrets/<name>` (+ `region` when given) -> the
+    # full `sec_<base62>` summary.
     #
     # `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)
+    # `metadata` (`Hash[String, String]`) are passed through verbatim.
+    def create(name:, value:, region: nil, visibility: nil, metadata: nil)
       slug = require_project_slug
       body = { 'value' => Base64.strict_encode64(value) }
       body['visibility'] = visibility if visibility
@@ -97,34 +87,34 @@ module K9o
       HttpTransport.request(
         config: @config, method: 'POST',
         path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
-        query: { 'region' => region },
+        query: region_query(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:)
+    # `POST .../<name>?op=reveal-challenge`.
+    def reveal_challenge(name, region: nil)
       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 }
+        query: region_query(region, 'op' => 'reveal-challenge')
       )
     end
 
     # Reveal a secret's plaintext value using a single-use challenge from
-    # `reveal_challenge`. `GET .../<name>?region=<region>` with
+    # `reveal_challenge`. `GET .../<name>` 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:)
+    # plaintext (the reveal response's `value` is base64, symmetric with
+    # `create`'s encode) before returning it to the caller.
+    def reveal(name, challenge:, region: nil)
       slug = require_project_slug
       envelope = HttpTransport.request(
         config: @config, method: 'GET',
         path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
-        query: { 'region' => region },
+        query: region_query(region),
         headers: { 'X-K9O-Reveal-Challenge' => challenge }
       )
       data = envelope.data
@@ -135,67 +125,73 @@ module K9o
     end
 
     # Update a secret's value (bumps version) — owner-only.
-    # `PUT .../<name>?region=<region>`.
+    # `PUT .../<name>`.
     #
-    # LIVE-VERIFIED NARROWER than documented: the gateway returns only
+    # Narrower than a full summary: 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)
+    def update(name, value:, region: nil, 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 },
+        query: region_query(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>`.
+    # unchanged) — owner-only. `POST .../<name>?op=rotate`.
     #
-    # LIVE-VERIFIED undocumented shape: `{id, name, version, rotatedAt,
+    # Response shape: `{id, name, version, rotatedAt,
     # ledgerSequenceNumber}` — the route's OpenAPI schema doesn't document
     # this response at all.
-    def rotate(name, region:)
+    def rotate(name, region: nil)
       slug = require_project_slug
       HttpTransport.request(
         config: @config, method: 'POST',
         path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
-        query: { 'op' => 'rotate', 'region' => region }
+        query: region_query(region, 'op' => 'rotate')
       )
     end
 
     # Move (rename) a secret's hierarchical path — owner-only.
-    # `POST .../<name>?op=move&region=<region>` with `{newPath}`.
+    # `POST .../<name>?op=move` with `{newPath}`.
     #
-    # LIVE-VERIFIED undocumented shape: `{id, name, event}` (observed
+    # Response 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:)
+    def move(name, new_path:, region: nil)
       slug = require_project_slug
       HttpTransport.request(
         config: @config, method: 'POST',
         path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
-        query: { 'op' => 'move', 'region' => region },
+        query: region_query(region, 'op' => 'move'),
         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:)
+    # Retire a secret - owner-only. `DELETE .../<name>`; any 2xx is success
+    # (204 No Content maps to `data: nil`).
+    def delete(name, region: nil)
       slug = require_project_slug
       HttpTransport.request(
         config: @config, method: 'DELETE',
         path: UrlGrammar.project_path(slug, "vault/secrets/#{enc(name)}"),
-        query: { 'region' => region }
+        query: region_query(region)
       )
     end
 
     private
 
+    def region_query(region, extra = {})
+      q = extra.dup
+      q['region'] = region if region
+      q
+    end
+
     def require_project_slug
       Studio.require_project_slug(@config, 'kibo.vault.secrets')
     end
@@ -206,8 +202,8 @@ module K9o
   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
+  # Currently just `secrets` ; a `zk_deks` accessor
+  # (`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
@@ -220,7 +216,7 @@ module K9o
 
   # `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
+  # 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

data/lib/k9o/version.rb

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

data/sig/k9o/gate.rbs

@@ -1,11 +1,12 @@
-# RBS signatures for the `client.gate` namespace (additions).
+# RBS signatures for the `client.gate` namespace.
 
 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
+    def sign_up: (email: String, password: String, ?display_name: String?) -> Envelope
+    def sign_in: (email: String, password: String) -> Envelope
+    # The refresh token is required: the gateway answers 400 without it.
+    def sign_out: (refresh_token: String) -> Envelope
+    def whoami: () -> Envelope
+    def refresh_token: (refresh_token: String) -> Envelope
   end
 end