knoxcall 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0e94c9fc8dddb7499ae737f1288460901462ee09a16e054ab8838790053742f
-  data.tar.gz: 4a60f8582629bd101f4c52e6dc63158d05d7cda054edd12530ec1a7a76311b0a
+  metadata.gz: 78a17cfe7bcdbb2f1a56bc7f115d6f75cd4e9d56cde413e27808c9d9bb948fd0
+  data.tar.gz: 06ed43b2bd4f26379b89c0aea34c6d057f39a5cc7e5c52b4d9b57deccbb14121
 SHA512:
-  metadata.gz: 878547713c90dc595e4a780407a085ec2e0fe6790e725328f0e9d17fd7504822af2d11b41993a18a6a0c0bad07d0da110e5e75eb102c7c479ae74ff4a886b78f
-  data.tar.gz: 483c686963824b3b52bc94a01cb65b022841b12ec974a308ec1302436c3877aa6051b59cddc657e8fb74e6274e1793061d40643a900fe2d621c0e88e355f6491
+  metadata.gz: 5e247d3e650af82c5ee9df3ac668a8736219769a91575facd8a62d397c3316c9a49088c95c36818775df8ef829c026c940147ffb9f512df3bb626cc4be7b65c9
+  data.tar.gz: fd40ea3558e70ed9a1d9dd9fdf3ac560c90606582849124c4a02d0ba9c6d35fed8f80a3b216e8f9955f5abac97714625a85d9deb7501d6c1ed0fab13bfefe967

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 KnoxCall
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -1,3 +1,440 @@
-# knoxcall
+# knoxcall-ruby
 
-This name is reserved by KnoxCall (https://knoxcall.com). The official KnoxCall SDK will be published here. This placeholder contains no code.
+Official KnoxCall API client for Ruby. Standards-based OAuth 2.1 + DPoP (RFC 9449) under the hood, zero dependencies (stdlib only) — your code just calls methods. Ruby >= 3.1.
+
+## Install
+
+Not yet published — install from the monorepo path (`gem "knoxcall", path: "../knoxcall-ruby"` in your Gemfile) or via a git checkout (`gem "knoxcall", git: "...", glob: "sdk/knoxcall-ruby/*.gemspec"`).
+
+## Quickstart
+
+```ruby
+require "knoxcall"
+
+# Credentials inline — tenant auto-discovered from the credential.
+client = KnoxCall::Client.new(client_id: "tk_xxxxxxxx", client_secret: "...")
+
+# Or zero-arg with the environment configured
+# (KNOXCALL_TENANT, KNOXCALL_CLIENT_ID, KNOXCALL_CLIENT_SECRET):
+client = KnoxCall::Client.new
+
+# A management call…
+page = client.routes.list
+puts "#{page['meta']['total']} routes"
+
+# …and a data-plane call through a route (slug preferred).
+res = client.call("api-orders", path: "/v1/customers")
+customers = JSON.parse(res.body)
+```
+
+The client is Mutex-safe: share a single instance across Puma / Sidekiq threads.
+
+## Authentication
+
+Pass credentials as flat constructor options:
+
+| Option | Use |
+|---|---|
+| `client_id:` + `client_secret:` | OAuth client-credentials grant (recommended for servers) |
+| `access_token:` / `api_key:` | a pre-acquired token or key — works with `kc_…` tokens and legacy `tk_…`/`AKE…` keys (two spellings, one behavior) |
+| `bootstrap:` | advanced: `ClientCredentials`, `AccessToken`, `OIDCTokenExchange` (workload identity), `StoredCredentials` (a specific credentials file/profile) |
+
+Passing conflicting credential options (e.g. `api_key:` and `client_id:`) raises `ArgumentError` at construction. Explicit options always beat the environment.
+
+With no explicit credentials, the SDK resolves from the environment in priority order:
+
+1. `KNOXCALL_ACCESS_TOKEN` (or `KNOXCALL_API_KEY`) env var
+2. Credentials file written by `knoxcall login` (`~/.knoxcall/credentials.json`)
+3. `KNOXCALL_CLIENT_ID` + `KNOXCALL_CLIENT_SECRET`
+
+### Log in once with the CLI
+
+This gem ships the `knoxcall` CLI (`gem install knoxcall`). It signs you in
+once in your browser; every script and worker on the machine picks the
+credential up automatically. No env vars, no keys in code:
+
+```bash
+knoxcall login                    # opens your browser (PKCE); prints the URL too
+knoxcall login --device           # headless/SSH machines: device-code flow
+knoxcall login --profile staging  # keep multiple accounts side by side
+knoxcall whoami                   # show the signed-in tenant
+knoxcall init                     # wrap-onboarding: confirm tenant + print a quickstart
+knoxcall logout                   # revoke and remove the stored credential
+```
+
+`knoxcall init` gets you wrapping a provider SDK. With no `--provider` it
+confirms who you are signed in as and prints a two-step quickstart (no writes).
+With `--provider stripe --secret-name wrap-stripe --host api.stripe.com` it moves
+a provider key into KnoxCall custody and prints the gateway `base_url` to point
+your SDK at — the key is read from the `KNOXCALL_WRAP_SECRET` env var (never a
+flag, so it stays out of your shell history) and is never printed. It works
+against the tenant you are already signed in to; it does not provision a tenant.
+
+Every KnoxCall SDK (python, node, go, php — and this gem) ships the same
+`knoxcall` executable with the same commands, writing the same
+`~/.knoxcall/credentials.json`, and every SDK reads that file — log in once
+with whichever CLI is on your PATH and all of them are signed in. Two SDKs
+installed side by side colliding on the executable name is harmless by
+construction.
+
+```ruby
+client = KnoxCall::Client.new  # zero config — tenant and base URL come from the login
+routes = client.routes.list
+```
+
+Credentials are stored in `~/.knoxcall/credentials.json` (file mode 0600). The
+stored tenant and base URL seed the client automatically; explicit constructor
+options or env vars always win. Access tokens refresh themselves, and refreshes
+are cross-process safe (file lock + atomic rotation of the single-use refresh
+token). If a refresh fails because the credential was revoked or expired, the
+SDK raises `AuthenticationError` telling you to run `knoxcall login` again.
+Select a non-default profile with `KNOXCALL_PROFILE` (or
+`bootstrap: KnoxCall::StoredCredentials.new(profile: "staging")`).
+
+### Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `KNOXCALL_TENANT` | tenant slug (optional — auto-discovered from the credential when unset) |
+| `KNOXCALL_ENVIRONMENT` | default environment for data-plane calls |
+| `KNOXCALL_CLIENT_ID` / `KNOXCALL_CLIENT_SECRET` | client-credentials grant |
+| `KNOXCALL_ACCESS_TOKEN` / `KNOXCALL_API_KEY` | pre-acquired token (ACCESS_TOKEN wins) |
+| `KNOXCALL_BASE_URL` | management API base override (legacy alias: `KNOXCALL_API_BASE_URL`) |
+| `KNOXCALL_PROXY_BASE_URL` | data-plane base override |
+| `KNOXCALL_CREDENTIALS_FILE` | credentials file path override (default `~/.knoxcall/credentials.json`) |
+| `KNOXCALL_PROFILE` | credentials-file profile to use (default `default`) |
+
+Pass `sandbox: true` to target the isolated Test data plane (`sandbox.knoxcall.com` management host, `sandbox-{tenant}.knoxcall.com` proxy host) with a `tk_test_` key.
+
+### Security notes
+
+- **A pre-acquired `access_token:` / `api_key:` is not auto-renewed.** It carries no refresh token, so the SDK sends it as-is until the server rejects it with a 401 — there is no silent refresh. For durable, self-renewing auth use `client_id:` + `client_secret:` (client-credentials) or log in with `knoxcall login` (the stored refresh token is rotated for you under a cross-process lock).
+- **Plaintext transport is flagged.** If the resolved management base URL *or* the data-plane proxy URL is `http://` to a non-loopback host, the client emits a one-time warning to `$stderr` that credentials and tokens will be sent unencrypted. `http://localhost` (and other loopback addresses) is the normal dev case and stays silent — use `https://` everywhere else.
+- **Loose credentials-file permissions are flagged.** On POSIX, if `~/.knoxcall/credentials.json` is readable by group or other, the SDK warns once to `chmod 600` it (it holds a refresh token). The check is skipped on Windows, where confidentiality rests on the `%USERPROFILE%` ACL rather than mode bits. These warnings never raise and never change behavior.
+
+## DPoP — sender-constrained tokens
+
+For higher-security tenants, enable DPoP (RFC 9449):
+
+```ruby
+client = KnoxCall::Client.new(tenant: "acme", dpop: "always")
+```
+
+The SDK generates an ES256 keypair, binds the access token to it via the `cnf.jkt` claim, and signs a fresh proof JWT per request — token, management, and data-plane alike. Stolen tokens become useless without the keypair.
+
+In the default `"auto"` mode the SDK starts with plain Bearer tokens and upgrades to DPoP automatically when the OAuth client record has `require_dpop` set (the token endpoint answers `invalid_dpop_proof`; the SDK generates a keypair, retries once, and operates as DPoP from then on). `dpop: "never"` opts out — if the server issues a DPoP-bound token anyway, the SDK raises `KnoxCall::TokenError` rather than 401-looping.
+
+## Data plane
+
+`client.call` proxies a request through a KnoxCall route to your upstream and returns the raw `Net::HTTPResponse` — the upstream's status belongs to you; the SDK never turns it into an error. Reference routes by **slug** — the write-once machine handle set on the route. Slugs are immutable (rename-proof, unlike names) and portable across tenants (unlike UUIDs). UUIDs also work; bare names are legacy.
+
+```ruby
+# GET
+res = client.call("api-orders", path: "/users")
+
+# POST with a body, targeting a specific environment
+res = client.call("api-orders",
+                  method: "POST",
+                  path: "/v1/charges",
+                  body: { amount: 2000, currency: "usd" },
+                  environment: "staging")
+
+res.code       # => "201"
+res.body       # raw body string
+```
+
+`path` is the **upstream** path. On a KnoxCall cloud tenant host the data plane is served under `/api` (`https://{tenant}.knoxcall.com/api/<path>`); the SDK adds that prefix itself whenever the proxy base is a cloud tenant host with no path of its own, and uses any other base verbatim (self-hosted, or an override that already carries a path). So `/api/v2/tickets` reaches an upstream path that itself begins with `/api`.
+
+A per-call `timeout:` overrides the client default.
+
+### Bound routes
+
+State the route (and optional defaults) once with `client.route`, then use plain HTTP verbs:
+
+```ruby
+printnode = client.route("api-printnode", environment: "production")
+
+res = printnode.get("/computers")
+res = printnode.post("/printjobs", body: job)
+res = printnode.request("DELETE", "/printjobs/42")
+# per-call options still override the bound defaults:
+res = printnode.get("/computers", environment: "staging")
+```
+
+The handle holds no state beyond the defaults — retries, token refresh, and 401 re-mint behave exactly as on `call`.
+
+### Ephemeral proxy
+
+One-shot proxying without a pre-configured route — the proxy resolves `{{ token: "..." }}` expressions in flight:
+
+```ruby
+res = client.ephemeral("https://api.stripe.com/v1/charges", method: "POST", body: payload)
+```
+
+### Route-aware interception (preview)
+
+Send an untouched third-party SDK's traffic through the Route that covers it —
+and through the ephemeral proxy where no Route does — with no per-SDK wiring:
+
+```ruby
+knox = KnoxCall::Client.new(api_key: api_key)
+stop = knox.wrap.intercept!(hosts: ["api.resend.com"])   # hosts with NO Route still covered (ephemeral)
+stop.ready                                                # first manifest loaded
+
+Net::HTTP.get(URI("https://api.hubapi.com/crm/v3/objects/contacts")) # any Net::HTTP caller, via the covering Route
+stop.uninstall
+```
+
+Per request: the kill switch (`KNOXCALL_INTERCEPT=off`), KnoxCall's own hosts
+and route-around rules go direct; a Route in the manifest covering host + path
+goes through that Route (the Route injects the stored secret — no provider
+credential travels); a host in `hosts:` with no Route goes through the
+ephemeral proxy; everything else is untouched. Turn a Route's **Intercept**
+toggle on and it takes effect on the next request after the 60 s TTL, or on
+the next refusal, with no code change. Per-host options:
+`hosts: { "api.resend.com" => { credential: { secret: "resend-key" } } }`
+(escrow) or `{ unavailable: :direct }` (transit only: send direct when
+KnoxCall is unreachable; the default is fail closed). `require_context: true`
+limits interception to code inside `knox.wrap.routed { }`.
+
+`intercept!` is **opt-in and experimental**: it prepends `Net::HTTP#request`,
+which reaches Faraday's default adapter, `rest-client`, `httparty` and raw
+Net::HTTP. Not reached: Typhoeus, Curb, `http.rb` (their own socket layer) —
+point those SDKs at `gateway_url`. The same decisions are available without
+the process-wide seam: `knox.wrap.faraday_connection(routes: :auto)` for an
+SDK that takes an injected connection (controls on `conn.knoxcall`), and
+`conn.builder.insert_before(Faraday::Adapter, *knox.wrap.faraday_middleware(hosts: [...]))`
+for a stack the SDK builds itself.
+
+This is a convenience, not a security boundary: it patches a process global
+and composes with other Net::HTTP patchers (WebMock, APM agents) in install
+order. Route mode is the custody path — the key never enters your process.
+
+#### What the SDK reports about uncovered calls, and how to turn it off
+
+**Reporting is on by default.** When the interceptor sends a call direct
+because no Route covers its host and you did not list the host, and that call
+carries a credential header (`Authorization`, `X-Api-Key`, or any name ending
+in `-api-key`, `-token`, `-secret` or `-auth`), the SDK counts it. About once a
+minute, the SDK reports the counts to KnoxCall
+(`POST /v1/wrap/egress-observations`) with its own credential. The dashboard
+uses the report to show which credentials still leave your process outside
+KnoxCall custody.
+
+**What is sent.** Each report carries the host, the first path segment, the
+method, the credential header's **name**, a count, and first/last-seen times.
+The header's **value** is never sent, and neither are the query string, the
+body, or any deeper path.
+
+**How to turn it off.** Pass `observe_uncovered: false` when you install, or set
+`KNOXCALL_OBSERVE_UNCOVERED=off` in the environment. Nothing is reported while
+`KNOXCALL_INTERCEPT=off`. If your key lacks `routes:read`, the first report is
+refused, you get one warning, and reporting stops. `on_observation_flush:` receives the
+server's `{accepted, dropped}` after each report.
+
+## Pagination
+
+The server wraps every JSON response in `{data, meta}` and paginates with `page`/`per_page` (default 20, cap 100). Single-object methods return the unwrapped Hash; paginated lists return the envelope; a few endpoints (environments, agents, crypto keys, PKI, dynamic-DB, OAuth clients, client credentials, route environments) return plain Arrays and take no page params.
+
+```ruby
+page = client.secrets.list(page: 2, per_page: 50)
+page["data"]                  # => [...]
+page["meta"]["total"]         # => 137
+page["meta"]["total_pages"]   # => 3
+page["meta"]["request_id"]    # for support
+
+# Walk every page transparently — block form or lazy Enumerator:
+client.secrets.each { |secret| puts secret["name"] }
+names = client.secrets.each.map { |s| s["name"] }
+first_ten = client.routes.each(per_page: 5).take(10) # fetches only 2 pages
+```
+
+`each` fetches page by page until `page >= meta.total_pages` (or an empty page). Sub-lists have `each_*` twins: `routes.each_log(id)`, `webhooks.each_log(id)`, `vaults.each_token(name)`.
+
+## Resources
+
+One-liner per area:
+
+```ruby
+# Routes
+route = client.routes.create(name: "orders", target_base_url: "https://api.example.com")
+logs  = client.routes.get_logs(route["id"])
+
+# Route field-actions (declarative field-level encrypt/tokenize on the proxy path)
+action = client.routes.create_action(route["id"], direction: "request", action: "tokenize",
+                                                  selectors: ["$.card.number"], key_name: "cards-vault")
+
+# Secrets
+secret = client.secrets.create(name: "STRIPE_KEY", value: "sk_live_...")
+client.secrets.set_value(secret["id"], value: "sk_live_rotated", environment: "production")
+
+# OAuth2 provider secret (proxy injects the provider's access token upstream)
+oauth = client.secrets.create_oauth2(name: "GITHUB", provider: "github",
+                                     client_id: "cid", client_secret: "csec",
+                                     scopes: ["repo"])
+# Certificate / mTLS secret (certificate_type defaults to "pem")
+cert  = client.secrets.create_certificate(name: "UPSTREAM_MTLS",
+                                          certificate_content: pem, private_key: key)
+
+# Webhooks (create returns the once-only "secret_key" — store it)
+wh     = client.webhooks.create(name: "orders-hook", url: "https://hooks.example.com/knox",
+                                event_types: ["request.error"])
+types  = client.webhooks.list_event_types
+result = client.webhooks.test(wh["id"])
+
+# Clients (calling machines) + credentials
+kc    = client.clients.create(name: "ci-runner", type: "server", ip_address: "203.0.113.9")
+creds = client.clients.list_credentials(kc["id"])
+
+# OAuth clients ("client_secret" shown once; "warning" carries the server's top-level warning)
+oc = client.oauth_clients.create(name: "svc")
+
+# Environments (bare array — no pagination)
+envs = client.environments.list
+
+# API keys (create returns the once-only plaintext "api_key")
+key = client.api_keys.create(name: "deploy-bot")
+
+# Account
+acct  = client.account.get
+usage = client.account.get_usage
+
+# Audit logs
+client.audit_logs.each(action: "secret.create") { |row| puts row["created_at"] }
+
+# Agents ("agent_secret" shown once)
+agent = client.agents.create("warehouse-agent")
+
+# Crypto — keyed transit encryption
+enc = client.crypto.encrypt("payments-key", plaintext: "hello")
+dec = client.crypto.decrypt("payments-key", ciphertext: enc["ciphertext"], format: "utf8")
+
+# Crypto — portable kc: encryption (structure-preserving, zero-config default key)
+sealed = client.crypto.encrypt_data({ card: "4242..." })
+opened = client.crypto.decrypt_data(sealed["ciphertext"])
+meta   = client.crypto.inspect("kc:1:enc:...")
+bundle = client.crypto.get_sealing_bundle          # public bits for browser-side sealing
+cap    = client.crypto.mint_client_token(action: "decrypt", data: "kc:1:enc:...")
+
+# PKI (cert + CRL are raw text, not JSON)
+root = client.pki.create_root("internal", { common_name: "Acme Internal CA" })
+pem  = client.pki.get_root_cert("internal")
+leaf = client.pki.issue_cert("internal", "servers", common_name: "db.acme.internal")
+
+# Vaults (tokenization)
+vault = client.vaults.create(name: "cards-vault")
+tok   = client.vaults.tokenize("cards-vault", value: "4242424242424242")
+val   = client.vaults.detokenize("cards-vault", tok["token"])
+
+# AI Gateway (secret -> gateway -> agent -> capability token).
+# provider + upstream_secret_id compose the upstream route. An agent created
+# with NEITHER those nor primary_route_id has no upstream and 502s on its first
+# data-plane call. provider is a plain string — the catalog is server-side,
+# and a bad value returns a 400 naming the valid set.
+secret = client.secrets.create(name: "anthropic-key", value: ENV["ANTHROPIC_API_KEY"])
+gw     = client.ai_gateway.create_gateway(name: "Prod", slug: "prod", budget_daily_usd: 50)
+agent  = client.ai_gateway.create_agent(gw["id"], name: "copilot", slug: "copilot",
+                                        provider: "anthropic", upstream_secret_id: secret["id"],
+                                        default_model: "claude-sonnet-5")
+minted = client.ai_gateway.mint_token(agent["id"], kind: "agent")
+# minted["token"] is the plaintext capability token — shown exactly once.
+# agent["agent_url"] is the base_url to point an AI SDK at.
+
+# Dynamic DB credentials
+minted = client.dynamic_db.mint("main-pg", "readonly")
+leases = client.dynamic_db.list_leases
+
+# Signup — credential-less, no client needed. Two steps: signup returns a claim
+# handle and emails a sign-in link; claim_signup collects the key once clicked.
+accepted = KnoxCall.signup({ email: "dev@example.com", tenant_name: "Acme Inc" })
+claim = KnoxCall.claim_signup(accepted["claim_handle"])  # poll until status == "ready"
+# claim["starter"]["api_key"]["api_key"] is shown exactly once — store it now.
+```
+
+## Wrapping third-party SDKs
+
+Route an *official* third-party SDK's traffic through KnoxCall so its provider key leaves your codebase — the SDK keeps its own serialization, retries, idempotency keys, and error types; only its HTTP transport is swapped. Two halves:
+
+**Escrow (all SDKs).** Hand the raw provider key to KnoxCall once; afterwards it is referenced by name and injected by the proxy.
+
+```ruby
+client.wrap.escrow(provider: "stripe", name: "stripe-live",
+                   value: "sk_live_...", hosts: ["api.stripe.com"])
+```
+
+**Transport (Faraday-based SDKs only).** `wrap.faraday_connection` returns a `Faraday::Connection` whose transport re-targets each request through KnoxCall's ephemeral proxy in transparent mode — the Ruby analogue of the Node SDK's `wrap.fetch()`. Hand it to any SDK that accepts an **injected Faraday connection**.
+
+```ruby
+conn = client.wrap.faraday_connection(url: "https://api.example.com")
+sdk  = SomeSDK.new(connection: conn)   # the SDK's own injection point
+```
+
+- **Transit mode (default)** lifts the wrapped SDK's own `Authorization` header out-of-band (never forwarded raw, never logged), with a both-must-agree Test/Live check against the client's `sandbox:` flag.
+- **Escrow mode** (`credential: { secret: "stripe-live" }`) keeps the raw key in KnoxCall custody — only the escrowed name travels.
+- **Route-around**: raw-card (PCI) endpoints are sent to the provider **directly**, untouched, by default; extend with `route_around:` and observe with `on_route_around:`.
+- **Promoted routes**: after you promote wrapped traffic to a durable route, pass `route: "<slug>"`, or opt into `auto_switch: true` (surfaced via `on_promoted:`).
+
+Requires the optional [`faraday`](https://rubygems.org/gems/faraday) gem — **KnoxCall itself has no runtime dependency on it** (`gem "faraday"` in your Gemfile); a clear `KnoxCall::Error` is raised if it is missing.
+
+> **Limitation.** Ruby has **no production-safe *generic* transport seam** (intercepting `Net::HTTP` globally is monkey-patching, deliberately refused). So `faraday_connection` works **only** with SDKs that let you inject a Faraday connection. An SDK that builds its own connection internally, or exposes only a **base-URL override** (Resend, Mailgun, Airtable, …), cannot use it — mint a base-URL gateway with `wrap.gateway_url` instead:
+
+```ruby
+gw     = client.wrap.gateway_url(secret: "stripe-live", host: "api.stripe.com")
+resend = Resend::Client.new(api_key: "placeholder", base_url: gw["base_url"])
+```
+
+## Webhook verification
+
+`KnoxCall::Client.construct_event` (also available as `client.construct_event` and `client.webhooks.construct_event`) verifies the delivery's HMAC-SHA256 signature and parses it into an event Hash in one step. Pass the raw body string — never re-serialized JSON.
+
+```ruby
+post "/webhooks/knoxcall" do
+  # Rack exposes inbound headers in request.env as HTTP_-prefixed CGI keys
+  # (HTTP_X_WEBHOOK_SIGNATURE); construct_event wants real header names, so
+  # strip the prefix and restore dashes.
+  headers = request.env
+                   .select { |k, _| k.start_with?("HTTP_") }
+                   .transform_keys { |k| k.sub(/\AHTTP_/, "").tr("_", "-") }
+  event = KnoxCall::Client.construct_event(request.body.read, headers, ENDPOINT_SECRET)
+
+  case event["event"]
+  when "audit.event"
+    log.info "audit: #{event['data']['action']}"
+  else # request.*
+    log.info "#{event['data']['route_name']} -> #{event['data']['response']['status']}"
+  end
+  200
+rescue KnoxCall::WebhookSignatureVerificationError
+  halt 400, "bad signature"
+end
+```
+
+Formats beyond the default `legacy` header (`stripe`, `github`, `slack`, `aws-sns`, `custom`) are selected with `format:`; the replay window defaults to 300s (`tolerance_seconds: nil` disables it); `custom` requires `header_name:`. All comparisons are constant-time. The boolean `verify_signature` helper remains for existing code.
+
+## Errors
+
+All API failures are typed subclasses of `KnoxCall::Error`:
+
+```ruby
+begin
+  client.secrets.create(name: "orders", value: secret)
+rescue KnoxCall::RateLimitError => e
+  sleep e.retry_after || 1
+rescue KnoxCall::ConflictError => e
+  logger.warn "already exists: #{e.code}"        # 409 — do not blind-retry
+rescue KnoxCall::ValidationError => e
+  logger.warn "invalid: #{e.fields.inspect}"     # 422 — per-field breakdown when present
+rescue KnoxCall::APIError => e
+  logger.error "#{e.status_code} #{e.code}: #{e.message} (request #{e.request_id})"
+end
+```
+
+Every `APIError` exposes `status_code`, `headers`, `body`, `code`/`type` (the server's
+machine-readable error code) and `request_id` (the `X-Request-Id` correlation id, header
+first then body) — branch on `e.code` rather than string-matching the message.
+
+Hierarchy: `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `ValidationError` (422, with `fields`), `RateLimitError` (429, with `retry_after`), `ServerError` (5xx), all under `APIError`; plus `SignupError` (with `status_code`/`error_type`/`request_id`), `WebhookSignatureVerificationError`, `TokenError`, and `NetworkError`/`ConnectionTimeoutError` for transport failures.
+
+## Retries & idempotency
+
+Management requests retry automatically on transport errors and HTTP 408/429/500/502/503/504 (never 409 — a real conflict does not resolve by replaying), with exponential half-jitter backoff and `Retry-After` honored up to 30s. Every mutating request carries a ULID `X-Idempotency-Key` that stays stable across retries, so replays are safe. A 401 purges the cached token and retries once with fresh credentials. Data-plane calls never replay a mutating request after it may have reached the wire. Tune with `retry_max_attempts:`, `retry_base_delay:`, `retry_max_delay:`.

data/exe/knoxcall

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# KnoxCall CLI — sign in once, every KnoxCall SDK on this machine picks it up.
+
+require "knoxcall/cli"
+
+exit KnoxCall::CLI.run(ARGV)