knoxcall 0.0.1 → 1.0.0

data/lib/knoxcall/resources/crypto.rb

@@ -0,0 +1,122 @@
+module KnoxCall
+  module Resources
+    class Crypto
+      include UnwrapsEnvelope
+
+      # Sentinel so #inspect can double as Object#inspect when called with no
+      # argument (consoles / p / rspec output) — see #inspect below.
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      def initialize(client) = @client = client
+
+      # -- Key management --
+
+      # Bare array — no pagination.
+      def list_keys = unwrap(@client.request("GET", "/v1/crypto/keys"))
+      def get_key(name) = unwrap(@client.request("GET", "/v1/crypto/keys/#{encode(name)}"))
+      def create_key(**input) = unwrap(@client.request("POST", "/v1/crypto/keys", body: input))
+      # Raise or lower the key's destroy safety latch. A version can only be
+      # destroyed while +deletion_allowed+ is true, and every new key ships with
+      # it false; destroy_key_version on a latched key is refused with a 409
+      # (deletion_not_allowed), which is a client error and must not be retried
+      # unchanged. Returns {"name" => String, "deletion_allowed" => Boolean}.
+      def update_key(name, deletion_allowed:) = unwrap(@client.request("PATCH", "/v1/crypto/keys/#{encode(name)}", body: { deletion_allowed: deletion_allowed }))
+      # Returns {"new_version" => Integer}.
+      def rotate_key(name) = unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/rotate", body: {}))
+      # Returns {"destroyed" => Integer} — the destroyed version.
+      def destroy_key_version(name, version) = unwrap(@client.request("DELETE", "/v1/crypto/keys/#{encode(name)}/versions/#{version}"))
+      # Returns {"pem", "jwk", "key_version"}. version travels as a query param.
+      def get_public_key(name, version: nil)
+        query = version ? { version: version } : nil
+        unwrap(@client.request("GET", "/v1/crypto/keys/#{encode(name)}/public-key", query: query))
+      end
+
+      # -- Keyed transit encryption --
+
+      # Returns {"ciphertext", "key_version"}.
+      def encrypt(name, **input) = unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/encrypt", body: input))
+      # Returns {"plaintext_b64", "key_version"} by default; pass
+      # format: "utf8" (a query param) for a decoded "plaintext" instead.
+      def decrypt(name, ciphertext:, format: nil)
+        query = format ? { format: format } : nil
+        unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/decrypt", query: query, body: { ciphertext: ciphertext }))
+      end
+      # Returns {"ciphertext", "key_version"}.
+      def rewrap(name, ciphertext:) = unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/rewrap", body: { ciphertext: ciphertext }))
+
+      # -- Portable kc: encryption (structure-preserving, top-level /v1) --
+      # Distinct from the keyed transit encrypt above: these take arbitrary
+      # JSON and return the same shape with scalar leaves swapped for
+      # portable, self-describing `kc:` ciphertext strings.
+
+      # Returns {"ciphertext" => <same shape, leaves encrypted>, "key", "key_version"}.
+      def encrypt_data(data, key: nil, role: nil)
+        body = { data: data }
+        body[:key] = key if key
+        body[:role] = role if role
+        unwrap(@client.request("POST", "/v1/encrypt", body: body))
+      end
+
+      # Returns {"plaintext" => <same shape, leaves decrypted>}.
+      def decrypt_data(data, role: nil)
+        body = { data: data }
+        body[:role] = role if role
+        unwrap(@client.request("POST", "/v1/decrypt", body: body))
+      end
+
+      # Metadata about a single `kc:` ciphertext string — no decryption.
+      # Returns {"encrypted", "scheme", "version", "datatype", "key_ref", "fingerprint"}.
+      # With no argument this behaves as Object#inspect so consoles still work.
+      def inspect(value = UNSET)
+        return super() if value.equal?(UNSET)
+        unwrap(@client.request("POST", "/v1/inspect", body: { value: value }))
+      end
+
+      # Mint a single-use, payload-pinned client-side capability token. Hand
+      # the returned "token" to a browser/agent so it can reveal exactly the
+      # bound data (a kc: ciphertext for "decrypt", a vault token for
+      # "detokenize") once, via POST /v1/client/{decrypt,detokenize}, without
+      # an API key. input: action:, data:, plus optional role:, ttl_seconds:.
+      # Returns {"token", "expires_at", "action"}.
+      def mint_client_token(**input) = unwrap(@client.request("POST", "/v1/client-tokens", body: input))
+
+      # The public bits a browser needs to seal values client-side (public
+      # key + key_ref). Your backend calls this and hands the JSON to the
+      # page; no private material is included.
+      def get_sealing_bundle(key: nil)
+        query = key ? { key: key } : nil
+        unwrap(@client.request("GET", "/v1/encrypt/sealing-bundle", query: query))
+      end
+
+      # -- Signing --
+
+      # Returns {"signature", "key_version"}.
+      def sign(name, **input) = unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/sign", body: input))
+      # Returns {"valid", "key_version"}.
+      def verify(name, **input) = unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/verify", body: input))
+
+      # -- JWT --
+
+      # Returns {"token", "key_version", "alg"}.
+      def sign_jwt(name, claims, header_overrides: nil)
+        body = { claims: claims }
+        body[:header_overrides] = header_overrides if header_overrides
+        unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/jwt", body: body))
+      end
+      # Returns {"valid"} plus, when valid, "claims"/"key_version"/"alg"/"kid"
+      # (or "error" when not).
+      def verify_jwt(name, token, expected: nil)
+        body = { token: token }
+        body[:expected] = expected if expected
+        unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/jwt/verify", body: body))
+      end
+
+      # -- Webhook signing --
+
+      # Returns {"signature_header" ("t=<unix>,v1=<hex>"), "timestamp_seconds",
+      # "key_version", "format" ("stripe")}.
+      def sign_webhook(name, **input) = unwrap(@client.request("POST", "/v1/crypto/keys/#{encode(name)}/webhook-sign", body: input))
+    end
+  end
+end

data/lib/knoxcall/resources/dynamic_db.rb

@@ -0,0 +1,68 @@
+module KnoxCall
+  module Resources
+    class DynamicDb
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # -- Connections --
+
+      # Bare array — no pagination.
+      def list = unwrap(@client.request("GET", "/v1/dyn-db-credentials"))
+      def get(name) = unwrap(@client.request("GET", "/v1/dyn-db-credentials/#{encode(name)}"))
+      def create(**input) = unwrap(@client.request("POST", "/v1/dyn-db-credentials", body: input))
+      # Returns {"updated" => <name String>}.
+      def update(name, **input) = unwrap(@client.request("PATCH", "/v1/dyn-db-credentials/#{encode(name)}", body: input))
+      # Returns {"deleted" => <name String>} (NOT a boolean — server contract).
+      def delete(name) = unwrap(@client.request("DELETE", "/v1/dyn-db-credentials/#{encode(name)}"))
+      # Returns {"rotated", "fingerprint_updated"}.
+      def rotate_ssh_key(name, ssh_private_key:, ssh_passphrase: nil, ssh_host_fingerprint: nil)
+        body = { ssh_private_key: ssh_private_key }
+        body[:ssh_passphrase] = ssh_passphrase if ssh_passphrase
+        body[:ssh_host_fingerprint] = ssh_host_fingerprint if ssh_host_fingerprint
+        unwrap(@client.request("POST", "/v1/dyn-db-credentials/#{encode(name)}/rotate-ssh-key", body: body))
+      end
+
+      # -- Roles --
+
+      # Bare array — no pagination.
+      def list_roles(connection_name) = unwrap(@client.request("GET", "/v1/dyn-db-credentials/#{encode(connection_name)}/roles"))
+      def create_role(connection_name, **input) = unwrap(@client.request("POST", "/v1/dyn-db-credentials/#{encode(connection_name)}/roles", body: input))
+      # Returns {"updated" => <role String>}.
+      def update_role(connection_name, role, **input) = unwrap(@client.request("PATCH", "/v1/dyn-db-credentials/#{encode(connection_name)}/roles/#{encode(role)}", body: input))
+      # Returns {"deleted" => <role String>}.
+      def delete_role(connection_name, role) = unwrap(@client.request("DELETE", "/v1/dyn-db-credentials/#{encode(connection_name)}/roles/#{encode(role)}"))
+
+      # -- Credential minting + leases --
+
+      # The response's "password" is shown exactly once — store it now.
+      # Returns {"username", "password", "expires_at", "lease_id" (Integer),
+      # "connection_name", "role_name"}.
+      def mint(connection_name, role, ttl_seconds: nil)
+        body = ttl_seconds ? { ttl_seconds: ttl_seconds } : {}
+        unwrap(@client.request("POST", "/v1/dyn-db-credentials/#{encode(connection_name)}/creds/#{encode(role)}", body: body))
+      end
+      # Returns {"leases" => [...], "total", "limit", "offset"} — this list
+      # really is limit/offset (inside data), the one list on the API that is
+      # neither page/per_page nor a bare array.
+      #
+      # Only LIVE leases are returned — status "active", "renewing" or
+      # "errored", i.e. every lease whose database user may still exist on your
+      # server. Expired and revoked leases have had their user dropped and are
+      # neither listed nor counted in "total". +connection+ is an exact match on
+      # the connection's name, scoped to the caller's Live/Test space.
+      #
+      # "errored" is included deliberately: renewal was abandoned after five
+      # consecutive failures, so nothing is refreshing or expiring that lease.
+      # It is also the set counted by the 409 "has N active credential lease(s)"
+      # a connection or role delete returns, so anything blocking a delete is
+      # listed here and can be revoked.
+      def list_leases(limit: nil, offset: nil, connection: nil)
+        q = { limit: limit, offset: offset, connection: connection }.compact
+        unwrap(@client.request("GET", "/v1/dyn-db-credentials/leases", query: q.empty? ? nil : q))
+      end
+      # Returns {"revoked" => <lease_id Integer>}.
+      def revoke_lease(lease_id) = unwrap(@client.request("POST", "/v1/dyn-db-credentials/leases/#{encode(lease_id)}/revoke", body: {}))
+    end
+  end
+end

data/lib/knoxcall/resources/environments.rb

@@ -0,0 +1,16 @@
+module KnoxCall
+  module Resources
+    class Environments
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # Bare array — no pagination.
+      def list = unwrap(@client.request("GET", "/v1/environments"))
+      def create(**input) = unwrap(@client.request("POST", "/v1/environments", body: input))
+      def update(env_id, **input) = unwrap(@client.request("PATCH", "/v1/environments/#{encode(env_id)}", body: input))
+      # Returns {"deleted" => true}.
+      def delete(env_id) = unwrap(@client.request("DELETE", "/v1/environments/#{encode(env_id)}"))
+    end
+  end
+end

data/lib/knoxcall/resources/logs.rb

@@ -0,0 +1,51 @@
+module KnoxCall
+  module Resources
+    # Request Logs — the per-call proxy log, and Merkle inclusion proofs.
+    #
+    # Distinct from {AuditLogs}, which is the CHANGE log (who edited what).
+    # This is the record of requests that went THROUGH the proxy, and {#proof}
+    # is the evidence that a given entry existed, unaltered, when it was
+    # anchored.
+    class Logs
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # One page of the request log feed. Params: +cursor+, +limit+,
+      # +route_id+, +status_code+. Returns the {data, meta} envelope.
+      #
+      # Keyset, not offset: ordering is ascending +cursor+ and stable across
+      # calls. Delivery is AT LEAST ONCE — dedupe on +request_id+.
+      # +meta.next_cursor+ is OPAQUE; pass it back verbatim. A +nil+
+      # +next_cursor+ means the feed is drained to the watermark, NOT that it
+      # has ended.
+      #
+      # Captured request/response BODIES are never returned here at any
+      # permission level. The identity fields (+src_ip+, +matched_client_id+,
+      # +identification_method+) require +log:read_identity+ and are ABSENT
+      # rather than nil when denied; +meta._redacted+ says so.
+      def list(**params) = @client.request("GET", "/v1/logs", query: params.empty? ? nil : params)
+
+      # Yield every row, walking the cursor transparently until the feed is
+      # drained to the watermark. Returns a lazy Enumerator when no block is
+      # given.
+      def each(**params, &block)
+        enum = paginate_cursor(params) { |p| list(**p) }
+        block ? enum.each(&block) : enum
+      end
+
+      # One request by its +request_id+ (the +X-Request-Id+ header value).
+      def get(request_id) = unwrap(@client.request("GET", "/v1/logs/#{encode(request_id)}"))
+
+      # Merkle inclusion proof for one request.
+      #
+      # Returns for every outcome — read +anchored+ and +verified+ rather than
+      # rescuing. +verified: false+ with +reason: "range_incomplete"+ is the
+      # expected result for an old entry whose anchored range has since been
+      # trimmed by retention, and is NOT a sign of tampering;
+      # +"root_mismatch"+ is. A proof is never returned alongside a failed
+      # verification.
+      def proof(request_id) = unwrap(@client.request("GET", "/v1/logs/#{encode(request_id)}/proof"))
+    end
+  end
+end

data/lib/knoxcall/resources/oauth_clients.rb

@@ -0,0 +1,34 @@
+module KnoxCall
+  module Resources
+    # OAuth client registry. These endpoints bypass the standard success()
+    # wrapper server-side: `data` has no accompanying meta, the list is NOT
+    # paginated, and create/rotate_secret carry a top-level `warning` string —
+    # surfaced here as an optional "warning" key on the returned Hash.
+    class OAuthClients
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # Bare array — no pagination.
+      def list = unwrap(@client.request("GET", "/v1/oauth-clients"))
+      def get(id) = unwrap(@client.request("GET", "/v1/oauth-clients/#{encode(id)}"))
+      # The response's "client_secret" (nil for public clients) is shown
+      # exactly once — store it now. A server-side warning, when present, is
+      # attached as the "warning" key.
+      def create(**input) = unwrap_with_warning(@client.request("POST", "/v1/oauth-clients", body: input))
+      # Returns {"id" => String}.
+      def update(id, **input) = unwrap(@client.request("PATCH", "/v1/oauth-clients/#{encode(id)}", body: input))
+      # The new "client_secret" is shown exactly once. The server's warning
+      # is attached as the "warning" key.
+      #
+      # Rotation is containment: every access and refresh token the OLD secret
+      # minted is revoked in the same transaction as the re-key, so they stop
+      # working immediately rather than at their TTL. A rotation whose
+      # revocation cannot complete is refused and the old secret keeps working —
+      # you never hold a new secret for a client whose old tokens are still live.
+      def rotate_secret(id) = unwrap_with_warning(@client.request("POST", "/v1/oauth-clients/#{encode(id)}/rotate-secret", body: {}))
+      # Returns {"revoked" => true}.
+      def revoke(id) = unwrap(@client.request("DELETE", "/v1/oauth-clients/#{encode(id)}"))
+    end
+  end
+end

data/lib/knoxcall/resources/opportunities.rb

@@ -0,0 +1,61 @@
+module KnoxCall
+  module Resources
+    # Promotion opportunities (GET/POST /v1/opportunities) — mirrors
+    # src/client-api/opportunities.ts.
+    #
+    # "We detected outbound API usage → create a route", from two sources
+    # (agent_monitor + gateway_traffic). #list refreshes gateway detection on
+    # read; #accept promotes a suggestion to a durable route + secret binding;
+    # #dismiss drops a pending suggestion.
+    #
+    # Each opportunity row is
+    # {id, source ("agent_monitor"|"gateway_traffic"), service,
+    #  destination_host, status ("pending"|"snoozed"|"onboarded"|"dismissed"),
+    #  confidence, suggested_route_json, evidence_json, accepted_route_id,
+    #  created_at, updated_at, acted_at}.
+    class Opportunities
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # List promotion opportunities (refreshes gateway detection on read).
+      # Paginated. Params: status ("pending"|"snoozed"|"onboarded"|
+      # "dismissed"), page (default 1), per_page (default 20, max 100).
+      # Returns the {data, meta} envelope.
+      def list(**params) = @client.request("GET", "/v1/opportunities", query: params.empty? ? nil : params)
+
+      # Yield every opportunity, walking pages transparently. Returns a lazy
+      # Enumerator when no block is given.
+      def each(**params, &block)
+        enum = paginate(params) { |p| list(**p) }
+        block ? enum.each(&block) : enum
+      end
+
+      # Promote a gateway suggestion to a durable route + secret binding.
+      #
+      # All body fields are optional: +collection_name+ (else the suggestion's,
+      # else "Wrapped APIs"), +environment+ (else the tenant default), +secret+
+      # (name/id to bind, else an escrowed wrap credential for the host is
+      # auto-bound), +header_name+ (default Authorization) and +value_prefix+
+      # (default "Bearer ").
+      #
+      # @return [Hash] unwrapped {opportunity_id, route: {id, slug, name},
+      #   collection_id, environment}
+      def accept(id, collection_name: nil, environment: nil, secret: nil,
+                 header_name: nil, value_prefix: nil)
+        body = {}
+        body[:collection_name] = collection_name unless collection_name.nil?
+        body[:environment]     = environment     unless environment.nil?
+        body[:secret]          = secret          unless secret.nil?
+        body[:header_name]     = header_name      unless header_name.nil?
+        body[:value_prefix]    = value_prefix     unless value_prefix.nil?
+        unwrap(@client.request("POST", "/v1/opportunities/#{encode(id)}/accept", body: body))
+      end
+
+      # Dismiss a pending suggestion.
+      #
+      # @return [Hash] unwrapped {opportunity_id, status: "dismissed"}
+      def dismiss(id) = unwrap(@client.request("POST", "/v1/opportunities/#{encode(id)}/dismiss"))
+    end
+  end
+end

data/lib/knoxcall/resources/pki.rb

@@ -0,0 +1,41 @@
+module KnoxCall
+  module Resources
+    class Pki
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # Bare array of CA roots — no pagination.
+      def list_roots = unwrap(@client.request("GET", "/v1/pki/roots"))
+      # Returns {"root" => CARoot, "intermediate_not_after" => ISO string}.
+      def create_root(name, subject) = unwrap(@client.request("POST", "/v1/pki/roots", body: { name: name, subject: subject }))
+      # Raw PEM text (text/x-pem-file) — no JSON wrapper.
+      def get_root_cert(name) = raw_text(@client.request("GET", "/v1/pki/roots/#{encode(name)}/cert"), "CA certificate")
+      # Returns {"intermediate_id", "not_after"}.
+      def rotate_intermediate(name) = unwrap(@client.request("POST", "/v1/pki/roots/#{encode(name)}/rotate-intermediate", body: {}))
+      # Raw CRL text — no JSON wrapper.
+      def get_crl(name) = raw_text(@client.request("GET", "/v1/pki/roots/#{encode(name)}/crl"), "CRL")
+      # Bare array of roles — no pagination.
+      def list_roles(root_name) = unwrap(@client.request("GET", "/v1/pki/roots/#{encode(root_name)}/roles"))
+      def create_role(root_name, **input) = unwrap(@client.request("POST", "/v1/pki/roots/#{encode(root_name)}/roles", body: input))
+      # Issue a leaf certificate under a role. The "private_key_pem" is shown
+      # exactly once — store it now. Returns {"serial_hex", "cert_pem",
+      # "private_key_pem", "ca_chain_pem", "not_before", "not_after"}.
+      def issue_cert(root_name, role, **input) = unwrap(@client.request("POST", "/v1/pki/roots/#{encode(root_name)}/issue/#{encode(role)}", body: input))
+      # Returns {"revoked" => Boolean}.
+      def revoke_cert(root_name, serial_hex, reason: nil)
+        body = { serial_hex: serial_hex }
+        body[:reason] = reason if reason
+        unwrap(@client.request("POST", "/v1/pki/roots/#{encode(root_name)}/revoke", body: body))
+      end
+
+      private
+
+      # The cert/CRL endpoints return raw text, not the JSON envelope.
+      def raw_text(response, what)
+        raise Error, "expected raw #{what} text but got a JSON response" unless response.is_a?(String)
+        response
+      end
+    end
+  end
+end

data/lib/knoxcall/resources/roles.rb

@@ -0,0 +1,27 @@
+module KnoxCall
+  module Resources
+    # Read-only role catalog (IaC plan §6 item 1.3).
+    #
+    # Roles are created and edited on the MFA-gated admin surface; /v1 exposes
+    # them so `api_keys.create(role_ids: [...])` can be written in code instead
+    # of by copying a UUID out of a browser URL bar. The rules a role grants are
+    # deliberately not exposed.
+    class Roles
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # Paginated. Params: subject_kind ("api_key" | "user"), page, per_page.
+      # Only roles whose applies_to includes "api_key" may be passed in
+      # `role_ids` when creating a key. Returns the {data, meta} envelope.
+      def list(**params) = @client.request("GET", "/v1/roles", query: params.empty? ? nil : params)
+
+      # Yield every role, walking pages transparently. Returns a lazy
+      # Enumerator when no block is given.
+      def each(**params, &block)
+        enum = paginate(params) { |p| list(**p) }
+        block ? enum.each(&block) : enum
+      end
+    end
+  end
+end

data/lib/knoxcall/resources/routes.rb

@@ -0,0 +1,53 @@
+module KnoxCall
+  module Resources
+    class Routes
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # Paginated. Params: page (default 1), per_page (default 20, max 100),
+      # plus endpoint filters. Returns the envelope:
+      # {"data" => [...], "meta" => {"total", "page", "per_page", "total_pages", "request_id"}}.
+      def list(**params) = @client.request("GET", "/v1/routes", query: params.empty? ? nil : params)
+
+      # Yield every route, walking pages transparently. Returns a lazy
+      # Enumerator when no block is given.
+      def each(**params, &block)
+        enum = paginate(params) { |p| list(**p) }
+        block ? enum.each(&block) : enum
+      end
+
+      def get(route_id) = unwrap(@client.request("GET", "/v1/routes/#{encode(route_id)}"))
+      def create(**input) = unwrap(@client.request("POST", "/v1/routes", body: input))
+      def update(route_id, **input) = unwrap(@client.request("PATCH", "/v1/routes/#{encode(route_id)}", body: input))
+      # Returns {"deleted" => true}.
+      def delete(route_id) = unwrap(@client.request("DELETE", "/v1/routes/#{encode(route_id)}"))
+
+      # Paginated request logs. Params: page, per_page, plus filters.
+      def get_logs(route_id, **params) = @client.request("GET", "/v1/routes/#{encode(route_id)}/logs", query: params.empty? ? nil : params)
+
+      # Yield every log row, walking pages transparently. Returns a lazy
+      # Enumerator when no block is given.
+      def each_log(route_id, **params, &block)
+        enum = paginate(params) { |p| get_logs(route_id, **p) }
+        block ? enum.each(&block) : enum
+      end
+
+      # Bare array — no pagination.
+      def list_environments(route_id) = unwrap(@client.request("GET", "/v1/routes/#{encode(route_id)}/environments"))
+      def upsert_environment(route_id, env_name, **input) = unwrap(@client.request("PUT", "/v1/routes/#{encode(route_id)}/environments/#{encode(env_name)}", body: input))
+      # Returns {"deleted" => true}.
+      def delete_environment(route_id, env_name) = unwrap(@client.request("DELETE", "/v1/routes/#{encode(route_id)}/environments/#{encode(env_name)}"))
+
+      # -- Relay field-actions (declarative field-level encrypt/decrypt/tokenize) --
+
+      # Bare array — no pagination.
+      def list_actions(route_id) = unwrap(@client.request("GET", "/v1/routes/#{encode(route_id)}/actions"))
+      # input: direction: ("request"|"response"), action: ("encrypt"|"decrypt"|
+      # "tokenize"|"detokenize"), selectors: [String], plus optional key_name:,
+      # data_role:, content_type:, sort_order:.
+      def create_action(route_id, **input) = unwrap(@client.request("POST", "/v1/routes/#{encode(route_id)}/actions", body: input))
+      def delete_action(route_id, action_id) = unwrap(@client.request("DELETE", "/v1/routes/#{encode(route_id)}/actions/#{encode(action_id)}"))
+    end
+  end
+end

data/lib/knoxcall/resources/secrets.rb

@@ -0,0 +1,98 @@
+module KnoxCall
+  module Resources
+    class Secrets
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # Paginated. Params: page (default 1), per_page (default 20, max 100),
+      # plus endpoint filters. Returns the {data, meta} envelope.
+      def list(**params) = @client.request("GET", "/v1/secrets", query: params.empty? ? nil : params)
+
+      # Yield every secret, walking pages transparently. Returns a lazy
+      # Enumerator when no block is given.
+      def each(**params, &block)
+        enum = paginate(params) { |p| list(**p) }
+        block ? enum.each(&block) : enum
+      end
+
+      # Fetch one secret's metadata. The value is never returned.
+      #
+      # The result carries an "environments" array — one entry per environment
+      # holding a value, ordered by environment name, each
+      # {environment_name, value_version, updated_at, expires_at_override}.
+      # "value_version" counts genuine value writes for that environment
+      # (starting at 1) and moves ONLY when the stored value changes:
+      # rotations, admin value/certificate updates and platform-managed
+      # custodial key rotation. It deliberately does not move for OAuth2 token
+      # refreshes, expiry-override edits, certificate metadata re-parsing, or a
+      # re-encryption of the same plaintext under a new tenant key. Compare it
+      # with the version your own last write returned to detect a rotation
+      # performed outside your tooling — "updated_at" cannot do that, because
+      # non-value writes move it too.
+      def get(secret_id) = unwrap(@client.request("GET", "/v1/secrets/#{encode(secret_id)}"))
+      def create(**input) = unwrap(@client.request("POST", "/v1/secrets", body: input))
+
+      # Create an OAuth2-provider secret (the proxy injects the provider's access
+      # token into upstream requests). The base #create cannot carry these
+      # fields, so POST the typed /v1/secrets/oauth2 route. Requires +name+,
+      # +provider+ and +client_id+; for most grant types also supply either
+      # +client_secret+ or +mtls_certificate_id+.
+      def create_oauth2(name:, provider:, client_id:, client_secret: nil,
+                        mtls_certificate_id: nil, scopes: nil, auth_url: nil,
+                        token_url: nil, grant_type: nil, username: nil,
+                        password: nil, collection_id: nil)
+        body = { name: name, provider: provider, client_id: client_id }
+        body[:client_secret]       = client_secret       unless client_secret.nil?
+        body[:mtls_certificate_id] = mtls_certificate_id unless mtls_certificate_id.nil?
+        body[:scopes]              = scopes              unless scopes.nil?
+        body[:auth_url]            = auth_url            unless auth_url.nil?
+        body[:token_url]           = token_url           unless token_url.nil?
+        body[:grant_type]          = grant_type          unless grant_type.nil?
+        body[:username]            = username            unless username.nil?
+        body[:password]            = password            unless password.nil?
+        body[:collection_id]       = collection_id       unless collection_id.nil?
+        unwrap(@client.request("POST", "/v1/secrets/oauth2", body: body))
+      end
+
+      # Create a certificate / mTLS secret. Requires +name+ and
+      # +certificate_content+ (PEM text, or base64 for binary formats);
+      # +certificate_type+ is one of pem|pfx|p12|crt|cer|key|pkcs7|p7b|p7c and
+      # defaults to "pem".
+      def create_certificate(name:, certificate_content:, private_key: nil,
+                            passphrase: nil, certificate_type: "pem",
+                            collection_id: nil)
+        body = { name: name, certificate_content: certificate_content,
+                 certificate_type: certificate_type }
+        body[:private_key]   = private_key   unless private_key.nil?
+        body[:passphrase]    = passphrase    unless passphrase.nil?
+        body[:collection_id] = collection_id unless collection_id.nil?
+        unwrap(@client.request("POST", "/v1/secrets/certificate", body: body))
+      end
+
+      def update(secret_id, **input) = unwrap(@client.request("PATCH", "/v1/secrets/#{encode(secret_id)}", body: input))
+      # Returns {"deleted" => true}.
+      def delete(secret_id) = unwrap(@client.request("DELETE", "/v1/secrets/#{encode(secret_id)}"))
+
+      # Rotate a secret's value for one environment.
+      #
+      # "value_version" in the result is the environment's version AFTER this
+      # write — 1 when this call stored the environment's first value,
+      # otherwise the previous version plus one. It is the version this call
+      # produced, so storing it has no read-after-write race with a concurrent
+      # rotation; compare it later against #get's
+      # environments[].value_version to detect a rotation performed outside
+      # your tooling.
+      def set_value(secret_id, value:, environment: nil)
+        body = { value: value }
+        body[:environment] = environment if environment
+        unwrap(@client.request("PUT", "/v1/secrets/#{encode(secret_id)}/value", body: body))
+      end
+
+      def get_oauth_token(secret_id, environment: nil)
+        query = environment ? { environment: environment } : nil
+        unwrap(@client.request("GET", "/v1/secrets/#{encode(secret_id)}/oauth2/token", query: query))
+      end
+    end
+  end
+end