knoxcall 0.0.1 → 1.0.0

data/lib/knoxcall/egress_observations.rb

@@ -0,0 +1,372 @@
+require "uri"
+require "time"
+require "ipaddr"
+require "knoxcall/errors"
+require "knoxcall/warnings"
+require "knoxcall/wrap_transport"
+
+module KnoxCall
+  # Uncovered-egress observations (PARITY §21.3; founder decisions 2026-09-26).
+  # Ruby mirror of +sdk/knoxcall-node/src/egress-observations.ts+.
+  #
+  # A route-aware seam sees every outbound request the process makes and
+  # sends only the covered ones through KnoxCall. The rest go direct — and
+  # among them are calls that carry a credential the platform does not hold:
+  # "uncovered egress". This module records those (host, first path segment,
+  # method, credential header NAME) in memory and reports the aggregate to
+  # +POST /v1/wrap/egress-observations+ ({Resources::Wrap#report_egress_observations}),
+  # so the dashboard can show a tenant which credentials are still leaving
+  # their process un-custodied.
+  #
+  # What is recorded is bounded on purpose, and the bound is the feature:
+  # names, never values — the credential header's NAME, never its value; the
+  # FIRST path segment only — never the query string, never the body, never a
+  # deeper path; counts per (host, segment, method, header) with first/last
+  # seen. Only a DIRECT decision with reason +:unlisted+ is observed —
+  # +:own_host+, +:route_around+, +:kill_switch+, +:outside_context+ and
+  # +:unparseable+ never are.
+  #
+  # Nothing here may add latency to, raise into, or alter the application's
+  # request: {EgressObservationReporter#record} is synchronous and cheap, the
+  # flush runs on a background thread (Ruby threads never keep a process
+  # alive), and every failure is swallowed after one warning. The reporter is
+  # process memory only.
+  module EgressObservations
+    # Exact (case-insensitive) header names that carry a credential. The
+    # shared fixture +sdk/fixtures/egress-observation.json+ pins this list.
+    CREDENTIAL_HEADER_ALLOWLIST = %w[
+      authorization proxy-authorization x-api-key api-key apikey x-apikey x-auth-token x-access-token
+      x-token token x-secret x-secret-key x-client-secret ocp-apim-subscription-key x-goog-api-key
+      x-amz-security-token x-shopify-access-token klaviyo-api-key x-hubspot-api-key
+    ].freeze
+
+    # A lower-cased header name ending in one of these also counts.
+    CREDENTIAL_HEADER_SUFFIXES = %w[-api-key -token -secret -auth].freeze
+
+    RANK = CREDENTIAL_HEADER_ALLOWLIST.each_with_index.to_h.freeze
+
+    # The methods the server accepts (upper-case); anything else is +invalid_method+.
+    METHODS = %w[GET HEAD POST PUT PATCH DELETE OPTIONS CONNECT TRACE].freeze
+
+    # The server's shape checks (src/wrap/egress-observations.ts).
+    HEADER_NAME_RE = /\A[a-z0-9][a-z0-9_-]*\z/
+    FIRST_SEGMENT_RE = %r{\A/[A-Za-z0-9._~!$&'()*+,;=:@%-]{0,255}\z}
+    MAX_HEADER_NAME_LENGTH = 64
+
+    # A credential in the first path segment (server #1022). Some APIs put one
+    # in the path (Telegram's /bot<id>:<secret>/...). The server stores such a
+    # segment as "/"; the SDK applies the SAME rule before sending.
+    MAX_PLAIN_FIRST_SEGMENT_LENGTH = 64
+    CREDENTIAL_SEGMENT_PREFIXES = [
+      /\Abot\d+:/i,
+      /\A(sk|pk|rk)_(live|test)_/i,
+      /\Ask-/,
+      /\Axox[abposr]-/,
+      /\Agh[pousr]_/,
+      /\Agithub_pat_/,
+      /\Aglpat-/,
+      /\Ashp(at|ca|pa|ss)_/,
+      /\A(AKIA|ASIA)[0-9A-Z]{12,}/,
+      /\AAIza[0-9A-Za-z_-]{20,}/,
+      /\AeyJ[A-Za-z0-9_-]{8,}/,
+      /\ASG\./
+    ].freeze
+
+    module_function
+
+    # Whether a header NAME (any casing) is credential-bearing.
+    def credential_header_name?(name)
+      n = name.to_s.strip.downcase
+      return false if n.empty? || n.length > MAX_HEADER_NAME_LENGTH || !HEADER_NAME_RE.match?(n)
+      return true if RANK.key?(n)
+
+      CREDENTIAL_HEADER_SUFFIXES.any? { |s| n.length > s.length && n.end_with?(s) }
+    end
+
+    # The credential header NAME to report for a request, or nil. Allowlist
+    # entries win in allowlist order; then the lexicographically smallest
+    # suffix match. A header whose value is empty after stripping never
+    # counts. Only names are read — values are looked at solely to discard
+    # empties and are never returned. +headers+ is a Hash (any casing; values
+    # String or Array) or an Enumerable of +[name, value]+ pairs.
+    def credential_header_name(headers)
+      best = nil
+      best_rank = CREDENTIAL_HEADER_ALLOWLIST.length + 1
+      best_suffix = nil
+      (headers || []).each do |raw_name, raw_value|
+        name = raw_name.to_s.strip.downcase
+        next if name.empty?
+        next if Array(raw_value).all? { |v| v.to_s.strip.empty? }
+
+        rank = RANK[name]
+        if rank
+          if rank < best_rank
+            best_rank = rank
+            best = name
+          end
+          next
+        end
+        next unless credential_header_name?(name)
+
+        best_suffix = name if best_suffix.nil? || name < best_suffix
+      end
+      best || best_suffix
+    end
+
+    # Whether a first segment (+/+ + one segment) looks like it carries a
+    # credential — the server's rule, on the raw and percent-decoded forms.
+    def first_segment_looks_like_credential?(first_segment)
+      raw = first_segment.to_s.delete_prefix("/")
+      return false if raw.empty?
+
+      decoded = raw.gsub(/%\h\h/) { |m| m[1..].hex.chr }.force_encoding(Encoding::UTF_8).scrub
+      [raw, decoded].uniq.any? do |s|
+        s.length > MAX_PLAIN_FIRST_SEGMENT_LENGTH ||
+          CREDENTIAL_SEGMENT_PREFIXES.any? { |re| re.match?(s) } ||
+          s.scan(/[A-Za-z0-9_-]{24,}/).any? { |run| [/[a-z]/, /[A-Z]/, /[0-9]/].count { |re| re.match?(run) } >= 2 }
+      end
+    end
+
+    # +/+ or +/<first path segment>+ of the URL — never the query, never
+    # deeper. Exactly one leading slash is consumed, so +//double+ reports +/+.
+    def first_segment(url)
+      path = begin
+        URI.parse(url.to_s).path.to_s
+      rescue URI::InvalidURIError
+        ""
+      end
+      "/#{path.delete_prefix('/').split('/', 2).first}"
+    end
+
+    # The whole classifier, pure: the four identifying fields for this
+    # request, or nil when it carries no credential-bearing header. The
+    # caller has ALREADY decided the request is direct + +:unlisted+.
+    def observation_for(url, method, headers)
+      host = begin
+        WrapTransport.normalize_host(URI.parse(url.to_s).host)
+      rescue URI::InvalidURIError
+        ""
+      end
+      return nil if host.nil? || host.empty? || ip_literal?(host) # the server drops it (ip_literal)
+
+      upper = (method.to_s.empty? ? "GET" : method.to_s).upcase
+      return nil unless METHODS.include?(upper)
+
+      segment = first_segment(url)
+      segment = "/" if first_segment_looks_like_credential?(segment) # reported as "/"; the entry is kept
+      return nil unless FIRST_SEGMENT_RE.match?(segment)
+
+      name = credential_header_name(headers)
+      return nil if name.nil?
+
+      { host: host, first_segment: segment, method: upper, header_name: name }
+    end
+
+    def ip_literal?(host)
+      IPAddr.new(host)
+      true
+    rescue IPAddr::Error, ArgumentError
+      false
+    end
+
+    # +KNOXCALL_OBSERVE_UNCOVERED=off|false|0+ turns the reporter off (read
+    # when a pipeline is built).
+    def disabled_by_env?
+      %w[off 0 false].include?(ENV.fetch("KNOXCALL_OBSERVE_UNCOVERED", "").strip.downcase)
+    end
+  end
+
+  # In-memory aggregation of uncovered-egress observations for ONE pipeline,
+  # flushed in the background. Thread-safe; bounded; never raises.
+  class EgressObservationReporter
+    DEFAULT_FLUSH_INTERVAL = 60.0
+    DEFAULT_FLUSH_AT_KEYS = 200
+    DEFAULT_MAX_KEYS = 1_000
+    DEFAULT_MAX_PER_REQUEST = 200
+
+    # @param report [#call] performs +POST /v1/wrap/egress-observations+ with at most +max_per_request+ observations
+    # @param on_flush [#call, nil] +{accepted:, dropped:}+ after each accepted report (never per observation)
+    def initialize(report, on_flush: nil, flush_interval: DEFAULT_FLUSH_INTERVAL, flush_at_keys: DEFAULT_FLUSH_AT_KEYS,
+                   max_keys: DEFAULT_MAX_KEYS, max_per_request: DEFAULT_MAX_PER_REQUEST, now: nil, rand: nil)
+      @report = report
+      @on_flush = on_flush
+      @interval = flush_interval
+      @flush_at = flush_at_keys
+      @max_keys = max_keys
+      @max_per = max_per_request
+      @now = now || -> { Time.now.to_f }
+      @rand = rand || -> { Kernel.rand }
+      @mutex = Mutex.new
+      @buffer = {}
+      @timer = nil
+      @flushing = false
+      @stopped = false
+      @forbidden = false
+      @warned_overflow = false
+      @warned_failed = false
+    end
+
+    # Distinct keys currently held.
+    def size = @mutex.synchronize { @buffer.size }
+    def stopped? = @stopped
+    # True once the endpoint answered 403: reporting is off for the life of this reporter.
+    def forbidden? = @forbidden
+
+    # The observations that would be sent now (a copy, in first-seen order).
+    def pending = @mutex.synchronize { @buffer.values.map { |e| wire(e) } }
+
+    # Record one uncovered credentialed call. Synchronous, never raises.
+    def record(obs)
+      return if @stopped || @forbidden
+
+      key = [obs[:host], obs[:first_segment], obs[:method], obs[:header_name]]
+      at = @now.call
+      flush_now = false
+      arm = false
+      warn_overflow = false
+      @mutex.synchronize do
+        hit = @buffer[key]
+        if hit
+          hit[:count] += 1
+          hit[:last_seen] = at
+          return
+        end
+        if @buffer.size >= @max_keys
+          warn_overflow = !@warned_overflow
+          @warned_overflow = true
+        else
+          @buffer[key] = { host: key[0], first_segment: key[1], method: key[2], header_name: key[3], count: 1,
+                           first_seen: at, last_seen: at }
+          if @buffer.size >= @flush_at
+            flush_now = true
+          else
+            arm = @timer.nil?
+          end
+        end
+      end
+      if warn_overflow
+        Warnings.warn_once("KNOXCALL_EGRESS_OBSERVATIONS_OVERFLOW",
+                           "KnoxCall: more than #{@max_keys} distinct uncovered-egress observations are pending; " \
+                           "new ones are dropped until the next flush.")
+      end
+      if flush_now
+        Thread.new { flush }.tap { |t| t.name = "knoxcall-egress-observations" }
+      elsif arm
+        arm_timer
+      end
+      nil
+    rescue StandardError
+      # best-effort: telemetry must never reach the application's request.
+      nil
+    end
+
+    # Send what is pending now, synchronously, inside the SDK's own suppressed
+    # scope so the report is never itself intercepted. A concurrent flush
+    # returns immediately. Never raises: a 403 ends reporting for good
+    # (warned once); any other failure drops the batch (warned once) and is
+    # never retried in a loop.
+    def flush
+      batch = nil
+      @mutex.synchronize do
+        return if @flushing || @forbidden || @buffer.empty?
+
+        @flushing = true
+        cancel_timer_locked
+        batch = @buffer.values.map { |e| wire(e) }
+        @buffer.clear
+      end
+      begin
+        suppressed { deliver(batch) }
+      ensure
+        @mutex.synchronize { @flushing = false }
+      end
+      nil
+    end
+
+    # Stop the timer and flush once more. Idempotent.
+    def stop
+      return if @stopped
+
+      @stopped = true
+      @mutex.synchronize { cancel_timer_locked }
+      flush
+      nil
+    end
+
+    private
+
+    def deliver(batch)
+      batch.each_slice(@max_per) do |chunk|
+        begin
+          res = @report.call(chunk)
+        rescue PermissionDeniedError
+          # The key lacks routes:read: reporting is off for good. Anything
+          # recorded from here on is dropped at the door.
+          @forbidden = true
+          @mutex.synchronize { @buffer.clear }
+          Warnings.warn_once("KNOXCALL_EGRESS_OBSERVATIONS_FORBIDDEN",
+                             "KnoxCall: the credential cannot report uncovered-egress observations (HTTP 403 — it " \
+                             "lacks routes:read); reporting is off for this interceptor. Grant the scope, or pass " \
+                             "observe_uncovered: false to silence this.")
+          return
+        rescue StandardError => e
+          # best-effort: the batch is dropped, never retried in a loop, never
+          # surfaced into the application's own request.
+          unless @warned_failed
+            @warned_failed = true
+            Warnings.warn_once("KNOXCALL_EGRESS_OBSERVATIONS_FAILED",
+                               "KnoxCall: reporting uncovered-egress observations failed (#{e.class}: #{e.message}); " \
+                               "the batch was dropped.")
+          end
+          return
+        end
+        next unless @on_flush
+
+        begin
+          @on_flush.call(accepted: (res && (res["accepted"] || res[:accepted])).to_i,
+                         dropped: (res && (res["dropped"] || res[:dropped])).to_i)
+        rescue StandardError
+          # A caller's hook must never break the reporter.
+          nil
+        end
+      end
+    end
+
+    def suppressed(&block)
+      if defined?(KnoxCall::InterceptContext)
+        KnoxCall::InterceptContext.suppressed(&block)
+      else
+        yield
+      end
+    end
+
+    def arm_timer
+      delay = [0.001, @interval * (1 + (@rand.call * 0.2 - 0.1))].max # ±10 %
+      @mutex.synchronize do
+        return if @stopped || @timer
+
+        @timer = Thread.new do
+          sleep delay
+          @mutex.synchronize { @timer = nil }
+          flush
+        rescue StandardError
+          nil
+        end
+        @timer.name = "knoxcall-egress-observations-timer"
+      end
+    end
+
+    def cancel_timer_locked
+      t = @timer
+      @timer = nil
+      t&.kill unless t.equal?(Thread.current)
+    end
+
+    def wire(e)
+      { host: e[:host], first_segment: e[:first_segment], method: e[:method], header_name: e[:header_name],
+        count: e[:count], first_seen: iso(e[:first_seen]), last_seen: iso(e[:last_seen]) }
+    end
+
+    def iso(ts) = Time.at(ts).utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+  end
+end

data/lib/knoxcall/errors.rb

@@ -0,0 +1,304 @@
+require "json"
+
+module KnoxCall
+  class Error < StandardError; end
+
+  # Raised by credential auto-detection when NO usable credential is found —
+  # no explicit creds (flat options or bootstrap:), no KNOXCALL_ACCESS_TOKEN /
+  # KNOXCALL_API_KEY / KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET, and no
+  # `knoxcall login` credentials file. A subclass of the base KnoxCall::Error —
+  # this SDK's bootstrap error, as there is no separate BootstrapError class —
+  # so existing `rescue KnoxCall::Error` keeps working, but distinctly typed so
+  # callers can branch on "not logged in — offer KnoxCall.login" versus a
+  # genuine misconfiguration (PARITY §1/§14). Also raised by the interactive
+  # login helpers when prompting would be unsafe (no TTY / CI / opt-out).
+  class NotAuthenticatedError < Error; end
+
+  class APIError < Error
+    attr_reader :status_code, :headers, :body
+    # Machine-readable error code — the server envelope's `error.type` (Shape A)
+    # or the bare `error` code string (flat Shape C). +nil+ when the body carried
+    # no code. Branch on this rather than string-matching the message.
+    attr_reader :code
+    # Correlation id for KnoxCall server logs — the `X-Request-Id` response
+    # header when present, else the id carried in the body. +nil+ if neither.
+    attr_reader :request_id
+
+    def initialize(message, status_code, headers: nil, body: nil, code: nil, request_id: nil)
+      super("KnoxCall API error #{status_code}: #{message}")
+      @status_code = status_code
+      @headers = headers || {}
+      @body = body
+      @code = code
+      @request_id = request_id
+    end
+
+    # Alias for #code — the canonical /v1 envelope names this field `type`,
+    # so callers that think in server terms can read `e.type`.
+    def type = @code
+  end
+
+  class AuthenticationError < APIError; end
+  class PermissionDeniedError < APIError; end
+  # Deprecated: pre-release name (also shadows Ruby's ::PermissionError when
+  # the module is included). Use PermissionDeniedError. Remove before 2.0.
+  PermissionError = PermissionDeniedError
+
+  # 402 — a plan/billing limit was hit. Two error types share this status:
+  # "plan_limit" (a counted quota was reached) and "plan_feature" (the
+  # capability itself is not on the tier). The mapping is on STATUS, so both
+  # land here.
+  # Distinct from PermissionDeniedError (403) so a caller can show an
+  # "upgrade" prompt rather than an "access denied" one. Carries #code /
+  # #type / #request_id like the other typed errors.
+  class PaymentRequiredError < APIError; end
+
+  class NotFoundError < APIError; end
+
+  # 409 — the request conflicts with server state (e.g. a duplicate name, or an
+  # idempotency-key reuse with a different body). Retrying verbatim will not
+  # resolve it, so the client never replays a 409.
+  class ConflictError < APIError; end
+
+  # 422 — the request body failed server-side validation. When the server
+  # returns a per-field breakdown it is available via #fields.
+  class ValidationError < APIError
+    # Per-field validation messages ({field => [msg, ...]}) when the server
+    # supplied them, else +nil+.
+    def fields
+      @body.is_a?(Hash) ? @body["fields"] : nil
+    end
+  end
+
+  class RateLimitError < APIError
+    # Server-requested delay in seconds, if a Retry-After header was sent.
+    def retry_after
+      v = @headers["retry-after"]
+      v && v.to_f
+    end
+  end
+
+  class ServerError < APIError; end
+
+  # A refusal from the AI *data plane* (+POST {agent_url}/…+), typed.
+  #
+  # WHY IT IS ITS OWN CLASS. The data plane is not the Management API: it
+  # answers <tt>{error, error_description, code}</tt> with the machine-readable
+  # code in BOTH +error+ and +code+ (AIGW-163), while the management plane
+  # answers the nested <tt>{"error" => {"type", "message", "request_id"}}</tt>.
+  # A +code+ of "budget_exceeded" and a +code+ of "not_found" come from
+  # different contracts, and the status alone cannot tell them apart.
+  #
+  # The SDK does not make the data-plane call for you — that is the design: you
+  # point an existing provider client at the agent's +agent_url+ and it works
+  # unchanged. So this class is paired with KnoxCall.ai_gateway_error_from,
+  # which types whatever that client hands back.
+  #
+  # A subclass of APIError (and so of the base Error), so an existing
+  # <tt>rescue KnoxCall::APIError</tt> still catches it (PARITY §1).
+  class AIGatewayError < APIError
+    # The human sentence. Rewritten whenever a clearer wording is found —
+    # branch on #code, never on this.
+    attr_reader :error_description
+    # Whole seconds from +Retry-After+, or +nil+.
+    #
+    # Absence is meaningful: the gateway sends no header rather than a guess, so
+    # +nil+ means "back off on your own schedule", never "retry now".
+    attr_reader :retry_after
+
+    def initialize(message, status_code, error_description:, retry_after: nil, **kwargs)
+      super(message, status_code, **kwargs)
+      @error_description = error_description
+      @retry_after = retry_after
+    end
+  end
+
+  # Does this parsed body look like the AI data plane's envelope?
+  #
+  # +error+ and +code+ must both be present AND equal: the pre-AIGW-163 auth
+  # shape had a +code+ that was not the +error+, and accepting it would make
+  # +code+ mean two things again.
+  def self.ai_gateway_error_body?(body)
+    return false unless body.is_a?(Hash)
+
+    body["error"].is_a?(String) &&
+      body["code"].is_a?(String) &&
+      body["error_description"].is_a?(String) &&
+      body["error"] == body["code"]
+  end
+
+  # Type a refusal a provider client received from an agent's data-plane URL.
+  #
+  # Returns +nil+ when +body+ is not the data plane's envelope, so a caller
+  # falls through to its own handling rather than being handed a mislabelled
+  # error:
+  #
+  #   res = Net::HTTP.post(URI("#{agent['agent_url']}/v1/messages"), payload)
+  #   if res.code.to_i >= 400
+  #     err = KnoxCall.ai_gateway_error_from(res.code.to_i, JSON.parse(res.body), res)
+  #     sleep(err.retry_after || 60) if err&.code == "budget_exceeded"
+  #     raise err || "HTTP #{res.code}"
+  #   end
+  #
+  # +headers+ accepts a Hash or anything with +[]+ (a Net::HTTPResponse), or nil.
+  def self.ai_gateway_error_from(status, body, headers = nil)
+    return nil unless ai_gateway_error_body?(body)
+
+    read = lambda do |name|
+      next nil if headers.nil?
+
+      value = begin
+        headers[name] || headers[name.downcase]
+      rescue StandardError
+        nil
+      end
+      value.is_a?(String) ? value : nil
+    end
+
+    raw_retry = (read.call("Retry-After") || "").strip
+    # An HTTP-date Retry-After is legal but is not delta-seconds; nil is the
+    # right reading of one we cannot use.
+    retry_after = raw_retry.match?(/\A\d+\z/) ? raw_retry.to_i : nil
+    request_id = read.call("X-Request-Id")
+    request_id = body["request_id"] if request_id.nil? && body["request_id"].is_a?(String)
+
+    AIGatewayError.new(
+      body["error_description"],
+      status,
+      error_description: body["error_description"],
+      retry_after: retry_after,
+      code: body["code"],
+      request_id: request_id,
+      headers: headers.is_a?(Hash) ? headers : nil,
+      body: body
+    )
+  end
+
+  # The token endpoint returned something unusable (non-JSON 200 from an edge
+  # proxy, missing access_token, a DPoP-bound token this SDK can't use, ...).
+  class TokenError < Error; end
+
+  # Transport-level failure — the request may never have reached the server.
+  class NetworkError < Error; end
+  class ConnectionTimeoutError < NetworkError; end
+
+  # A webhook delivery failed verification in Client.construct_event (missing
+  # header, signature mismatch, stale timestamp, non-JSON body). The message
+  # says what failed without ever echoing the signature or the secret.
+  class WebhookSignatureVerificationError < Error; end
+
+  # Raised by the wrap Faraday transport (wrap.faraday_connection) when a
+  # wrapped SDK's provider key contradicts the client's sandbox flag —
+  # both-must-agree (PARITY §18): a Stripe TEST key can never be wrapped by a
+  # LIVE client (or vice versa), and a publishable (pk_…) key is refused
+  # outright. Also raised for a malformed route-around host. A subclass of the
+  # base KnoxCall::Error so existing `rescue KnoxCall::Error` keeps working; it
+  # is a configuration mistake, never a transport failure.
+  class WrapSandboxMismatchError < Error; end
+
+  # KnoxCall.signup failed — validation, slug conflict, rate limit, or an
+  # unexpected response body. Carries the server's machine-readable error
+  # type (e.g. "slug_taken") and the request id for support.
+  class SignupError < Error
+    attr_reader :status_code, :error_type, :request_id, :body
+
+    def initialize(message, status_code:, error_type: nil, request_id: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @error_type = error_type
+      @request_id = request_id
+      @body = body
+    end
+  end
+
+  # KnoxCall.exchange_token failed — the RFC 8693 exchange at
+  # POST /v1/oauth/token was refused, or returned a body with no
+  # access_token. +error_type+ is the RFC 6749 §5.2 code: "invalid_grant",
+  # "invalid_target", "unsupported_grant_type", "invalid_request" or
+  # "server_error".
+  class TokenExchangeError < Error
+    attr_reader :status_code, :error_type, :body
+
+    def initialize(message, status_code:, error_type: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @error_type = error_type
+      @body = body
+    end
+  end
+
+  # A WorkloadCredentialProvider assertion source returned bytes that were
+  # already spent on a previous exchange, so sending them could only have been
+  # refused. This is a caller-side configuration error, not a credential
+  # rejection, and it says so: the message names the cause and what to do,
+  # because the alternative is a replay refusal from the server that reads like
+  # "your CI identity is not trusted".
+  class StaleAssertionError < Error; end
+
+  # Build the typed error for a >= 400 Net::HTTPResponse. Mirrors the Node
+  # SDK's errorFromResponse (sdk/knoxcall-node/src/error.ts).
+  def self.error_from_response(resp)
+    status = resp.code.to_i
+    data = begin
+      JSON.parse(resp.body.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+
+    headers = {}
+    resp.each_header { |k, v| headers[k.downcase] = v }
+
+    body = data.is_a?(Hash) ? data : {}
+    err = body["error"]
+
+    # The KnoxCall /v1 API returns errors as {error:{type,message,request_id}}
+    # (the `error` value is a HASH) — Shape A, the canonical envelope. We stay
+    # tolerant of the flat shapes some non-/v1 surfaces still use:
+    #   B: {error:"<message>", statusCode, errorId}
+    #   C: {error:"<code>", message}   — `error` is a CODE, `message` is human.
+    if err.is_a?(Hash)
+      msg = presence(err["message"]) || presence(err["type"]) || "HTTP #{status}"
+      code = err["type"].is_a?(String) ? err["type"] : nil
+      body_request_id = err["request_id"].is_a?(String) ? err["request_id"] : nil
+    else
+      # Flat shapes. Prefer a human `error_description`/`message` over the bare
+      # `error` (a code string in Shape C, a message in Shape B), so Shape C
+      # surfaces the human text — not the code — while still recording the code.
+      msg = presence(body["error_description"]) ||
+            presence(body["message"]) ||
+            presence(err) ||
+            "HTTP #{status}"
+      # AIGW-163: the AI data plane sends the code in BOTH `error` and `code`.
+      # Prefer the explicit `code` — a future surface could carry one that is
+      # not mirrored, and reading the mirror would silently lose it.
+      code = presence(body["code"]) || (err.is_a?(String) ? err : nil)
+      body_request_id =
+        (body["request_id"].is_a?(String) ? body["request_id"] : nil) ||
+        (body["errorId"].is_a?(String) ? body["errorId"] : nil)
+    end
+
+    # Correlation id: prefer the X-Request-Id response header (now always emitted
+    # by the API) then fall back to the id carried in the body.
+    request_id = headers["x-request-id"] || body_request_id
+
+    klass = case status
+            when 401 then AuthenticationError
+            when 402 then PaymentRequiredError
+            when 403 then PermissionDeniedError
+            when 404 then NotFoundError
+            when 409 then ConflictError
+            when 422 then ValidationError
+            when 429 then RateLimitError
+            when 500.. then ServerError
+            else APIError
+            end
+    klass.new(msg, status, headers: headers, body: data, code: code, request_id: request_id)
+  end
+
+  # A non-empty String, else nil — collapses "" and non-strings to nil so the
+  # message/code fallbacks skip them.
+  def self.presence(v)
+    v if v.is_a?(String) && !v.empty?
+  end
+  private_class_method :presence
+end