knoxcall 0.0.1 → 1.0.0

data/lib/knoxcall/wrap_faraday_adapter.rb

@@ -0,0 +1,119 @@
+require "faraday"
+require "uri"
+require "knoxcall/wrap_transport"
+require "knoxcall/intercept_pipeline"
+
+module KnoxCall
+  module Resources
+    class Wrap
+      # A Faraday adapter that routes a wrapped third-party SDK's requests
+      # through KnoxCall — the Ruby analogue of the Node SDK's +wrap.fetch()+.
+      # It is the TERMINAL adapter in a Faraday connection: instead of
+      # performing the HTTP call itself it hands each request to the shared
+      # {InterceptPipeline}, which sends it through {KnoxCall::Client#call}
+      # (route mode — the Route the intercept manifest names) or
+      # {KnoxCall::Client#ephemeral} (transparent mode), the same way
+      # {KnoxCall::BoundRoute} delegates to +call+ — no second HTTP stack.
+      # Direct decisions (route-around, own hosts, the kill switch, a D4
+      # fallback) perform the ORIGINAL request via a plain Faraday adapter.
+      #
+      # Built and wired by {KnoxCall::Resources::Wrap#faraday_connection}. For
+      # SDKs that build their own stack see {Wrap#faraday_middleware}; for the
+      # opt-in process-wide seam see {Wrap#intercept!}.
+      #
+      # This file references +Faraday+ constants at load time, so it is required
+      # lazily (only once the +faraday+ gem is confirmed present) — the base SDK
+      # never depends on Faraday.
+      class FaradayAdapter < Faraday::Adapter
+        # @param app the next app in the Faraday stack (the terminal endpoint)
+        # @param options [Hash] a single positional options Hash:
+        #   - +:pipeline+ [InterceptPipeline] the shared pipeline (built by faraday_connection), or
+        #     the {InterceptPipeline#initialize} keywords to build one (+:client+ required)
+        #   - +:direct_adapter+ the Faraday adapter used for direct calls (default Faraday.default_adapter)
+        def initialize(app, options = {})
+          super(app)
+          @direct_adapter = options[:direct_adapter]
+          @pipeline = options[:pipeline] ||
+                      InterceptPipeline.new(all_hosts: true, **options.reject { |k, _| %i[pipeline direct_adapter].include?(k) })
+          @mutex = Mutex.new
+        end
+
+        # The pipeline (ready / refresh / manifest / stop).
+        attr_reader :pipeline
+
+        def call(env)
+          # Capture the request BEFORE super: super installs env.response,
+          # after which some Faraday versions read env.body as the response body.
+          url = env.url.to_s
+          method = env.method.to_s.upcase
+          body = env.body
+          request_headers = env.request_headers
+          headers = {}
+          request_headers.each { |k, v| headers[k] = v }
+          super
+
+          decision = @pipeline.decide(url, method)
+          if decision.direct?
+            # Decided BEFORE sending — never "try KnoxCall then fall back",
+            # which would already have transited. The ORIGINAL request is
+            # forwarded untouched.
+            @pipeline.direct_decided(decision, url, method: method, headers: headers)
+            return direct_call(env, method, body, request_headers)
+          end
+
+          resp = @pipeline.send(decision, url: url, method: method, headers: headers, body: body)
+          return direct_call(env, method, body, request_headers) if resp == InterceptPipeline::DIRECT
+
+          finish(env, resp)
+        rescue KnoxCall::ConnectionTimeoutError => e
+          # Map KnoxCall transport failures onto Faraday's own error types so a
+          # wrapped SDK's retry/rescue logic (which knows Faraday, not KnoxCall)
+          # still fires.
+          raise Faraday::TimeoutError, e.message
+        rescue KnoxCall::NetworkError => e
+          raise Faraday::ConnectionFailed, e.message
+        end
+
+        private
+
+        # Convert the Net::HTTPResponse returned by ephemeral()/call() into a
+        # Faraday response and hand control back up the stack.
+        def finish(env, resp)
+          headers = {}
+          resp.each_header { |k, v| headers[k] = v }
+          save_response(env, resp.code.to_i, resp.body, headers, resp.message)
+          @app.call(env)
+        end
+
+        # Perform the ORIGINAL request against the real upstream, untouched,
+        # via a plain Faraday adapter — never through KnoxCall.
+        def direct_call(env, method, body, request_headers)
+          conn = @mutex.synchronize { @direct_conn ||= build_direct_connection }
+          resp = conn.run_request(method.downcase.to_sym, env.url, body, request_headers)
+          # `headers`, not `response_headers` — the latter is a Faraday::Env
+          # method, not a Faraday::Response one.
+          save_response(env, resp.status, resp.body, resp.headers, resp.reason_phrase)
+          @app.call(env)
+        end
+
+        def build_direct_connection
+          spec = @direct_adapter || Faraday.default_adapter
+          Faraday.new { |f| f.adapter(*Array(spec)) }
+        end
+      end
+    end
+  end
+end
+
+# Advanced use: reference the adapter by symbol in a hand-built Faraday stack
+# (`f.adapter :knoxcall, pipeline: ...`). faraday_connection references the
+# adapter CLASS directly, so this symbol registration is a convenience only.
+begin
+  Faraday::Adapter.register_middleware(knoxcall: KnoxCall::Resources::Wrap::FaradayAdapter)
+rescue StandardError
+  # best-effort: registration is purely for the `:knoxcall` shorthand; the
+  # supported entrypoint (faraday_connection) uses the class directly, so a
+  # register_middleware signature drift across Faraday versions must not break
+  # the feature.
+  nil
+end

data/lib/knoxcall/wrap_faraday_middleware.rb

@@ -0,0 +1,67 @@
+require "faraday"
+require "knoxcall/intercept_pipeline"
+
+module KnoxCall
+  module Resources
+    class Wrap
+      # A Faraday MIDDLEWARE (not an adapter) for stacks an SDK builds itself
+      # and lets you add middleware to: insert it anywhere above the adapter
+      # and a request the pipeline claims — a Route covers its host + path, or
+      # the host is listed — is answered from KnoxCall without ever reaching
+      # the SDK's own adapter; every other request continues down the stack
+      # untouched. Built by {Wrap#faraday_middleware}:
+      #
+      #   conn = SomeSDK.connection                          # an SDK-built Faraday stack
+      #   conn.builder.insert_before(Faraday::Adapter, *knox.wrap.faraday_middleware(hosts: ["api.resend.com"]))
+      #
+      # It shares {InterceptPipeline} with the adapter and the Net::HTTP seam,
+      # so the decisions are identical.
+      class FaradayMiddleware < Faraday::Middleware
+        # @param app the next app in the stack
+        # @param options [Hash] +pipeline:+ (an {InterceptPipeline}) or the
+        #   keyword arguments to build one (+client:+ required)
+        def initialize(app, options = {})
+          super(app)
+          @pipeline = options[:pipeline] || InterceptPipeline.new(**options.reject { |k, _| k == :pipeline })
+        end
+
+        def call(env)
+          url = env.url.to_s
+          method = env.method.to_s.upcase
+          decision = @pipeline.decide(url, method)
+          headers = {}
+          env.request_headers.each { |k, v| headers[k] = v }
+          if decision.direct?
+            @pipeline.direct_decided(decision, url, method: method, headers: headers)
+            return @app.call(env)
+          end
+
+          resp = @pipeline.send(decision, url: url, method: method, headers: headers, body: env.body)
+          return @app.call(env) if resp == InterceptPipeline::DIRECT
+
+          finish(env, resp)
+        rescue KnoxCall::ConnectionTimeoutError => e
+          raise Faraday::TimeoutError, e.message
+        rescue KnoxCall::NetworkError => e
+          raise Faraday::ConnectionFailed, e.message
+        end
+
+        private
+
+        # Short-circuit the stack with the Net::HTTPResponse the pipeline
+        # returned: the same completion an adapter performs.
+        def finish(env, resp)
+          headers = {}
+          resp.each_header { |k, v| headers[k] = v }
+          env.status = resp.code.to_i
+          env.reason_phrase = resp.message.to_s.strip
+          env.body = resp.body
+          env.response_headers = Faraday::Utils::Headers.new.tap { |h| h.update(headers) }
+          response = Faraday::Response.new
+          env.response = response
+          response.finish(env)
+        end
+      end
+    end
+  end
+end

data/lib/knoxcall/wrap_transport.rb

@@ -0,0 +1,139 @@
+require "uri"
+
+module KnoxCall
+  # Pure, transport-agnostic helpers behind the Ruby wrap transport
+  # ({KnoxCall::Resources::Wrap#faraday_connection}) — the analogue of the Node
+  # SDK's +src/wrap-transport.ts+. Deliberately free of any Faraday dependency
+  # so they load with the base SDK and stay unit-testable without the optional
+  # gem.
+  #
+  # A wrapped third-party SDK keeps its own serialization, retries, idempotency
+  # keys and error types; only its HTTP transport is swapped for one that
+  # re-targets each request through KnoxCall's ephemeral proxy in transparent
+  # mode. The provider credential the SDK sets on its +Authorization+ header is
+  # LIFTED out-of-band (transit mode, the default) or replaced by a named
+  # escrowed credential (escrow mode) — the raw key never forwards as a header
+  # and is never logged.
+  module WrapTransport
+    module_function
+
+    # Built-in route-around defaults. Mirrors the SERVER's raw-PAN refusal
+    # (src/client-api/ephemeral-proxy.ts PAN_ENDPOINT_DENYLIST) so a wrapped
+    # SDK's raw-card call is sent straight to the provider instead of
+    # hard-failing on the server-side 403. Deliberately conservative and
+    # identical in spirit to the Node DEFAULT_ROUTE_AROUND.
+    DEFAULT_ROUTE_AROUND = [
+      { host: "api.stripe.com", path_prefix: "/v1/tokens",
+        reason: "raw-card endpoint (PCI): sent direct to the provider" },
+      { host: "api.stripe.com", path_prefix: "/v1/sources",
+        reason: "raw-card endpoint (PCI): sent direct to the provider" }
+    ].freeze
+
+    # Upstream headers the shim must NOT forward through ephemeral(): the
+    # provider Authorization is lifted out-of-band; Host/Content-Length are
+    # recomputed by the transport.
+    DROP_FORWARDED = %w[authorization host content-length].freeze
+
+    # Read a rule value tolerating both symbol and string keys, so a
+    # caller-supplied Hash reads naturally either way.
+    def rule_value(rule, key)
+      return nil unless rule.is_a?(Hash)
+
+      rule.key?(key) ? rule[key] : rule[key.to_s]
+    end
+
+    # PARITY §21's host contract: lower-case, surrounding whitespace and IPv6
+    # brackets stripped, a single trailing dot stripped — so a trailing-dot
+    # FQDN ("api.stripe.com.") can't dodge an exact-match rule. The server's
+    # PAN denylist and the intercept manifest normalize the same way.
+    def normalize_host(host)
+      host.to_s.strip.downcase.delete_prefix("[").delete_suffix("]").sub(/\.\z/, "")
+    end
+
+    # The first route-around rule matching this URL, or +nil+. A trailing-dot
+    # FQDN ("api.stripe.com.") resolves to the same host but would dodge an
+    # exact-match rule — both sides are normalized, matching the server's PAN
+    # denylist and the Node wrapper.
+    def match_route_around(url, rules)
+      u = begin
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        return nil
+      end
+      host = normalize_host(u.host)
+      return nil if host.empty?
+
+      Array(rules).each do |r|
+        next if host != normalize_host(rule_value(r, :host))
+
+        prefix = rule_value(r, :path_prefix)
+        next if prefix && !u.path.to_s.start_with?(prefix.to_s)
+
+        return r
+      end
+      nil
+    end
+
+    # Validate caller-supplied route-around rules: a +host+ that isn't a bare
+    # DNS hostname (a scheme/port/path slipped in) can never match a parsed URL
+    # host and would silently disable the rule — fail loud instead. Mirrors the
+    # Node assertRouteAroundRules and the escrow allowed-hosts contract.
+    def assert_route_around_rules(rules)
+      Array(rules).each do |r|
+        h = rule_value(r, :host).to_s.strip
+        parsed = begin
+          URI.parse("https://#{h}").host.to_s
+        rescue URI::InvalidURIError
+          ""
+        end
+        next unless h.empty? || normalize_host(parsed) != normalize_host(h)
+
+        raise WrapSandboxMismatchError,
+              "invalid route_around host #{rule_value(r, :host).inspect}: " \
+              "expected a bare DNS hostname (no scheme, port, or path)."
+      end
+    end
+
+    # Both-must-agree (PARITY §18): a Stripe +sk_+/+rk_+ key's Test/Live prefix
+    # must match the client's sandbox flag, so a test key can never be wrapped
+    # by a live client (or vice versa). Publishable +pk_+ keys are rejected
+    # outright — they are not server credentials. Non-Stripe schemes we cannot
+    # classify are left alone. +authorization_value+ is the full header value,
+    # e.g. "Bearer sk_live_…".
+    def assert_key_matches_sandbox(authorization_value, sandbox)
+      return if authorization_value.nil? || authorization_value.to_s.empty?
+
+      sandbox = sandbox ? true : false
+      # Trim BEFORE stripping the scheme: a leading space would otherwise stop
+      # the anchored Bearer from matching, leaving the whole value in +token+
+      # and silently skipping the check (Node review regression #1).
+      token = authorization_value.to_s.strip.sub(/\ABearer\s+/i, "").strip
+      if token.match?(/\Apk_(?:test|live)_/)
+        raise WrapSandboxMismatchError,
+              "A Stripe publishable key (pk_…) is not a server credential and cannot be wrapped. " \
+              "Use a secret (sk_…) or restricted (rk_…) key."
+      end
+
+      m = /\A(?:sk|rk)_(test|live)_/.match(token)
+      return unless m # unknown / non-Stripe scheme — nothing to assert
+
+      key_is_test = m[1] == "test"
+      return if key_is_test == sandbox
+
+      raise WrapSandboxMismatchError,
+            "Provider key is a #{key_is_test ? 'TEST' : 'LIVE'} key but the KnoxCall client was " \
+            "constructed with sandbox=#{sandbox}. Test keys require sandbox:true, live keys require " \
+            "sandbox:false — construct a matching client."
+    end
+
+    # The upstream headers to forward (everything the SDK set except the dropped
+    # ones), keyed as the SDK supplied them.
+    def forwardable_headers(headers)
+      out = {}
+      headers.each do |k, v|
+        out[k] = v unless DROP_FORWARDED.include?(k.to_s.downcase)
+      end
+      out
+    end
+  end
+end

data/lib/knoxcall.rb

@@ -1 +1,45 @@
-raise LoadError, "knoxcall 0.0.1 is a name placeholder; the KnoxCall SDK release will replace it."
+require "knoxcall/errors"
+require "knoxcall/ulid"
+require "knoxcall/warnings"
+require "knoxcall/bootstrap"
+require "knoxcall/credentials_file"
+require "knoxcall/dpop"
+require "knoxcall/client"
+require "knoxcall/bound_route"
+require "knoxcall/signup"
+require "knoxcall/token_exchange"
+require "knoxcall/workload_provider"
+require "knoxcall/login"
+require "knoxcall/wrap_transport"
+require "knoxcall/intercept_resolver"
+require "knoxcall/intercept_store"
+require "knoxcall/egress_observations"
+require "knoxcall/intercept_pipeline"
+require "knoxcall/resources/unwraps_envelope"
+require "knoxcall/resources/routes"
+require "knoxcall/resources/secrets"
+require "knoxcall/resources/webhooks"
+require "knoxcall/resources/workflows"
+require "knoxcall/resources/clients"
+require "knoxcall/resources/oauth_clients"
+require "knoxcall/resources/environments"
+require "knoxcall/resources/api_keys"
+require "knoxcall/resources/roles"
+require "knoxcall/resources/account"
+require "knoxcall/resources/audit_logs"
+require "knoxcall/resources/logs"
+require "knoxcall/resources/agents"
+require "knoxcall/resources/crypto"
+require "knoxcall/resources/pki"
+require "knoxcall/resources/vaults"
+require "knoxcall/resources/dynamic_db"
+require "knoxcall/resources/ai_gateway"
+require "knoxcall/resources/wrap"
+require "knoxcall/resources/opportunities"
+
+module KnoxCall
+  VERSION = "0.1.0"
+  SDK_VERSION = "knoxcall-ruby/#{VERSION}"
+  DEFAULT_API_BASE = "https://api.knoxcall.com"
+  DEFAULT_CLOUD_HOST = "knoxcall.com"
+end

metadata

@@ -1,27 +1,87 @@
 --- !ruby/object:Gem::Specification
 name: knoxcall
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - KnoxCall
-bindir: bin
+autorequire:
+bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-27 00:00:00.000000000 Z
 dependencies: []
-description: This name is reserved by KnoxCall. The official SDK will be published
-  here.
-executables: []
+description: 'Ruby client for the KnoxCall multi-tenant API gateway and secrets platform:
+  OAuth 2.1 + DPoP auth, route proxying, secrets, vaults, PKI, crypto, AI Gateway,
+  and webhook verification.'
+email:
+executables:
+- knoxcall
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
+- exe/knoxcall
 - lib/knoxcall.rb
-homepage: https://knoxcall.com
+- lib/knoxcall/bootstrap.rb
+- lib/knoxcall/bound_route.rb
+- lib/knoxcall/cli.rb
+- lib/knoxcall/cli/ai.rb
+- lib/knoxcall/cli/ai_control.rb
+- lib/knoxcall/cli/common.rb
+- lib/knoxcall/cli/init.rb
+- lib/knoxcall/cli/login.rb
+- lib/knoxcall/cli/logout.rb
+- lib/knoxcall/cli/whoami.rb
+- lib/knoxcall/client.rb
+- lib/knoxcall/credentials_file.rb
+- lib/knoxcall/dpop.rb
+- lib/knoxcall/egress_observations.rb
+- lib/knoxcall/errors.rb
+- lib/knoxcall/intercept_patch.rb
+- lib/knoxcall/intercept_pipeline.rb
+- lib/knoxcall/intercept_resolver.rb
+- lib/knoxcall/intercept_store.rb
+- lib/knoxcall/login.rb
+- lib/knoxcall/resources/account.rb
+- lib/knoxcall/resources/agents.rb
+- lib/knoxcall/resources/ai_gateway.rb
+- lib/knoxcall/resources/api_keys.rb
+- lib/knoxcall/resources/audit_logs.rb
+- lib/knoxcall/resources/clients.rb
+- lib/knoxcall/resources/crypto.rb
+- lib/knoxcall/resources/dynamic_db.rb
+- lib/knoxcall/resources/environments.rb
+- lib/knoxcall/resources/logs.rb
+- lib/knoxcall/resources/oauth_clients.rb
+- lib/knoxcall/resources/opportunities.rb
+- lib/knoxcall/resources/pki.rb
+- lib/knoxcall/resources/roles.rb
+- lib/knoxcall/resources/routes.rb
+- lib/knoxcall/resources/secrets.rb
+- lib/knoxcall/resources/unwraps_envelope.rb
+- lib/knoxcall/resources/vaults.rb
+- lib/knoxcall/resources/webhooks.rb
+- lib/knoxcall/resources/workflows.rb
+- lib/knoxcall/resources/wrap.rb
+- lib/knoxcall/route_refusal.rb
+- lib/knoxcall/signup.rb
+- lib/knoxcall/token_exchange.rb
+- lib/knoxcall/ulid.rb
+- lib/knoxcall/warnings.rb
+- lib/knoxcall/workload_provider.rb
+- lib/knoxcall/wrap_faraday_adapter.rb
+- lib/knoxcall/wrap_faraday_middleware.rb
+- lib/knoxcall/wrap_transport.rb
+homepage: https://docs.knoxcall.com/api-reference
 licenses:
 - Apache-2.0
 metadata:
+  homepage_uri: https://docs.knoxcall.com/api-reference
+  source_code_uri: https://github.com/knoxcall/sdk-ruby
+  changelog_uri: https://github.com/knoxcall/sdk-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -36,7 +96,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: Placeholder for the official KnoxCall Ruby SDK.
+summary: Official Ruby SDK for the KnoxCall API
 test_files: []