k9o 1.2.0 → 1.4.0

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.4.0'
 end

data/lib/k9o.rb

@@ -29,6 +29,7 @@ require_relative 'k9o/url_grammar'
 require_relative 'k9o/region'
 require_relative 'k9o/http_transport'
 require_relative 'k9o/data'
+require_relative 'k9o/query'
 require_relative 'k9o/projects'
 require_relative 'k9o/gate'
 require_relative 'k9o/studio'
@@ -36,6 +37,9 @@ require_relative 'k9o/compute'
 require_relative 'k9o/ai'
 require_relative 'k9o/storage'
 require_relative 'k9o/realtime'
+require_relative 'k9o/streams'
+require_relative 'k9o/approvals'
+require_relative 'k9o/schema'
 require_relative 'k9o/migrations'
 require_relative 'k9o/functions'
 require_relative 'k9o/policies'

data/sig/k9o/ai.rbs

@@ -8,6 +8,10 @@ module K9o
     # { "embeddings" => Array[Array[Float]], "model" => String, "dimensions" => Integer }.
     def initialize: (untyped config) -> void
     def embed: (input: (String | Array[String]), ?model: String?) -> Envelope
+
+    # Only the fields given are sent. Returns an Envelope whose `data` is
+    # { "modelId" => String, "content" => String, "finishReason" => String, "usage" => Hash, "usageType" => String }.
+    def generate: (String prompt, ?model: String?, ?max_tokens: Integer?, ?temperature: Numeric?, ?usage_type: String?) -> Envelope
   end
 
   class K9oClient

data/sig/k9o/approvals.rbs

@@ -0,0 +1,49 @@
+# RBS signatures for `client.approvals`, `client.approval_policies` and `client.schema`.
+
+module K9o
+  module ApprovalChecks
+    def self.invalid: (String message, ?Hash[Symbol, untyped] context) -> KError
+    def self.check_limit: (untyped limit) -> void
+    def self.id_segment: (untyped value, String what) -> String
+    def self.reason!: (untyped reason) -> String
+    def self.predicate!: (untyped value, String field) -> Hash[untyped, untyped]
+    def self.enum!: (untyped value, Array[String] allowed, String field) -> String
+  end
+
+  class Approvals
+    def initialize: (untyped config) -> void
+    # Not paginated: only `limit` (1 to 200, default 50) caps the result.
+    def list: (?status: (String | Symbol)?, ?limit: Integer?) -> Envelope
+    def get: (String id) -> Envelope
+    # `status` on the answer stays "pending_approval" while more approvers are needed.
+    def approve: (String id, ?reason: String?) -> Envelope
+    def reject: (String id, reason: String) -> Envelope
+    # Failed rows are skipped without a report: compare `affectedIds` with what you intended.
+    def bulk: (action: (String | Symbol), criteria: Hash[(String | Symbol), untyped], ?reason: String?) -> Envelope
+  end
+
+  class ApprovalPolicies
+    COLLECTION_RE: Regexp
+
+    def initialize: (untyped config) -> void
+    def list: () -> Envelope
+    def create: (collection: String, operation: (String | Symbol), action: (String | Symbol), predicate: Hash[(String | Symbol), untyped]) -> Envelope
+    def delete: (String id) -> Envelope
+  end
+
+  class SchemaCollections
+    def initialize: (untyped config) -> void
+    def list: (?limit: Integer?, ?cursor: String?) -> Envelope
+  end
+
+  class Schema
+    attr_reader collections: SchemaCollections
+    def initialize: (untyped config) -> void
+  end
+
+  class K9oClient
+    attr_reader approvals: Approvals
+    attr_reader approval_policies: ApprovalPolicies
+    attr_reader schema: Schema
+  end
+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

data/sig/k9o/query.rbs

@@ -0,0 +1,26 @@
+# RBS signatures for `client.query`, `client.search` and the select builder's search methods.
+
+module K9o
+  module Query
+    type value = String | Integer | Float | bool | nil
+
+    # Rewrites :name placeholders to $n; returns [sql, positional values].
+    def self.translate_named_params: (String sql, Hash[(String | Symbol), untyped] named) -> [String, Array[value]]
+  end
+
+  module QueryMethods
+    # An Array binds positionally to $1, $2, ...; a Hash binds :name placeholders. `data` is the array of rows.
+    def query: (String sql, ?(Array[untyped] | Hash[(String | Symbol), untyped])? params) -> Envelope
+
+    def search: (String collection, column: String, q: String, ?language: String?, ?type: String?, ?limit: Integer?, ?cursor: String?) -> Envelope
+  end
+
+  class K9oClient
+    include QueryMethods
+  end
+
+  class SelectBuilder
+    def text_search: (String column, String query, ?language: String, ?type: (String | Symbol)) -> self
+    def vector_search: (String column, Array[Numeric] embedding, ?metric: (String | Symbol), ?limit: Integer?) -> self
+  end
+end

data/sig/k9o/region.rbs

@@ -2,9 +2,6 @@
 
 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.
@@ -17,3 +14,17 @@ module K9o
     attr_accessor regional_origin: String?
   end
 end
+
+module K9o
+  module UrlGrammar
+    # The org, family, region and apex of a gateway host (`acme.api-de01.corp.internal`), or nil for any other shape.
+    class ApiHost < Struct[untyped]
+      attr_reader org_slug: String?
+      attr_reader family: String
+      attr_reader region: String?
+      attr_reader apex: String
+    end
+
+    def self.parse_api_host: (String host) -> ApiHost?
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: k9o
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Kilimanjaro
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -39,6 +39,7 @@ files:
 - k9o.gemspec
 - lib/k9o.rb
 - lib/k9o/ai.rb
+- lib/k9o/approvals.rb
 - lib/k9o/audit.rb
 - lib/k9o/barbican.rb
 - lib/k9o/client.rb
@@ -57,16 +58,21 @@ files:
 - lib/k9o/orgs.rb
 - lib/k9o/policies.rb
 - lib/k9o/projects.rb
+- lib/k9o/query.rb
 - lib/k9o/realtime.rb
 - lib/k9o/region.rb
+- lib/k9o/schema.rb
 - lib/k9o/storage.rb
+- lib/k9o/streams.rb
 - lib/k9o/studio.rb
 - lib/k9o/url_grammar.rb
 - lib/k9o/vault.rb
 - lib/k9o/version.rb
 - sig/k9o/ai.rbs
+- sig/k9o/approvals.rbs
 - sig/k9o/gate.rbs
 - sig/k9o/migrations.rbs
+- sig/k9o/query.rbs
 - sig/k9o/region.rbs
 - sig/k9o/storage.rbs
 homepage: https://kilimanjaro.dev