knoxcall 0.0.1 → 1.0.0

data/lib/knoxcall/intercept_resolver.rb

@@ -0,0 +1,140 @@
+require "uri"
+require "set"
+require "knoxcall/wrap_transport"
+
+module KnoxCall
+  # The route-aware interception decision table — pure, no I/O
+  # (docs/internal/sdk-wrapping/route-aware-interception-plan.md §2.2, PARITY
+  # §21.1). One request in, one decision out: send it DIRECT (untouched),
+  # through a ROUTE (the manifest says an intercept-enabled Route covers this
+  # host + path; the Route injects the stored secret), or through the EPHEMERAL
+  # proxy (the caller listed the host, no Route covers it; the SDK's own
+  # credential is lifted out-of-band). The order of the rules is the feature.
+  #
+  # Every SDK's resolver passes the SAME fixtures — sdk/fixtures/intercept-
+  # resolver.json (spec/intercept_resolver_spec.rb runs them here) — so this is
+  # the Ruby copy of a contract whose reference is the Node SDK's
+  # src/intercept-resolver.ts, not a private heuristic.
+  module InterceptResolver
+    MODES = %i[direct route ephemeral].freeze
+    REASONS = %i[kill_switch unparseable own_host route_around outside_context
+                 manifest no_base_path_match no_route unlisted].freeze
+
+    # The resolver's answer for one request. +slug+ / +path+ / +entry+ are set
+    # in route mode only; +route_around_reason+ for a route-around match.
+    Decision = Struct.new(:mode, :reason, :host, :slug, :path, :entry, :route_around_reason,
+                          keyword_init: true) do
+      def direct? = mode == :direct
+      def route? = mode == :route
+      def ephemeral? = mode == :ephemeral
+    end
+
+    module_function
+
+    # KNOXCALL_INTERCEPT=off (or 0 / false): every interceptor and route-aware
+    # transport becomes pass-through, per request, with no deploy.
+    def kill_switch?
+      %w[off 0 false].include?(ENV.fetch("KNOXCALL_INTERCEPT", "").strip.downcase)
+    end
+
+    # KnoxCall's own domains are never intercepted, whatever a manifest or a
+    # host list says (anti-recursion).
+    def platform_host?(host)
+      host == "knoxcall.com" || host.end_with?(".knoxcall.com")
+    end
+
+    # Read a manifest-entry field tolerating string and symbol keys (the parsed
+    # manifest is string-keyed; a hand-built one may not be).
+    def entry_value(entry, key)
+      return nil unless entry.is_a?(Hash)
+
+      entry.key?(key.to_s) ? entry[key.to_s] : entry[key.to_sym]
+    end
+
+    # The request path with the route's base prefix removed (leading slash
+    # kept), or +nil+ when the request is not under the base. "/crm/v3" covers
+    # "/crm/v3" and "/crm/v3/x", never "/crm/v30" — the boundary is a path
+    # segment. Mirrors the server's rebasePath (src/lib/route-target-host.ts).
+    def rebase_path(request_path, base_path)
+      req_path = request_path.to_s.empty? ? "/" : request_path.to_s
+      if base_path.nil? || base_path == "/" || base_path == ""
+        return req_path.start_with?("/") ? req_path : "/#{req_path}"
+      end
+      return "/" if req_path == base_path
+      return nil unless req_path.start_with?("#{base_path}/")
+
+      rest = req_path[base_path.length..]
+      rest.empty? ? "/" : rest
+    end
+
+    # Manifest entries for a host in the order the server sorts them — longest
+    # base_path first, then base_path, then slug — so the first entry whose
+    # base covers the path is the longest-prefix, lowest-slug match.
+    def entries_for_host(manifest, host)
+      return [] if manifest.nil?
+
+      routes = entry_value(manifest, :routes) || []
+      routes.select { |e| WrapTransport.normalize_host(entry_value(e, :host)) == host }
+            .sort_by { |e| bp = entry_value(e, :base_path).to_s; [-bp.length, bp, entry_value(e, :slug).to_s] }
+    end
+
+    # Apply the decision table. First match wins.
+    #
+    # @param url [String] the request URL
+    # @param method [String] the HTTP method (carried for hooks; not a rule input today)
+    # @param hosts [Set<String>, :all] the caller's explicit host list (normalised),
+    #   or +:all+ for the explicit-transport form where every request is listed
+    # @param manifest [Hash, nil] the intercept manifest ({"routes" => [...]})
+    # @param own_hosts [Set<String>] the client's own hosts (management + data plane)
+    # @param route_around [Array<Hash>] route-around rules
+    # @param kill_switch [Boolean]
+    # @param require_context [Boolean] only intercept inside +routed { }+
+    # @param in_context [Boolean] whether this request is inside +routed { }+
+    # @return [Decision]
+    def resolve(url:, method:, hosts:, manifest:, own_hosts:, route_around:,
+                kill_switch: false, require_context: false, in_context: false)
+      _ = method
+      return Decision.new(mode: :direct, reason: :kill_switch, host: "") if kill_switch
+
+      u = begin
+        URI.parse(url.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+      unless u && %w[http https].include?(u.scheme.to_s.downcase)
+        return Decision.new(mode: :direct, reason: :unparseable, host: "")
+      end
+      host = WrapTransport.normalize_host(u.host)
+      return Decision.new(mode: :direct, reason: :unparseable, host: "") if host.empty?
+
+      if platform_host?(host) || own_hosts.include?(host)
+        return Decision.new(mode: :direct, reason: :own_host, host: host)
+      end
+
+      around = WrapTransport.match_route_around(url.to_s, route_around)
+      if around
+        return Decision.new(mode: :direct, reason: :route_around, host: host,
+                            route_around_reason: WrapTransport.rule_value(around, :reason))
+      end
+
+      return Decision.new(mode: :direct, reason: :outside_context, host: host) if require_context && !in_context
+
+      entries = entries_for_host(manifest, host)
+      entries.each do |entry|
+        rebased = rebase_path(u.path, entry_value(entry, :base_path))
+        next if rebased.nil?
+
+        path = u.query ? "#{rebased}?#{u.query}" : rebased
+        return Decision.new(mode: :route, reason: :manifest, host: host,
+                            slug: entry_value(entry, :slug), path: path, entry: entry)
+      end
+
+      listed = hosts == :all || hosts.include?(host)
+      if listed
+        return Decision.new(mode: :ephemeral, reason: entries.empty? ? :no_route : :no_base_path_match, host: host)
+      end
+
+      Decision.new(mode: :direct, reason: :unlisted, host: host)
+    end
+  end
+end

data/lib/knoxcall/intercept_store.rb

@@ -0,0 +1,203 @@
+require "knoxcall/errors"
+require "knoxcall/warnings"
+
+module KnoxCall
+  # The SDK-side copy of the intercept manifest — fetched, held, refreshed
+  # (route-aware-interception-plan.md §2.5; PARITY §21.1). One per transport /
+  # interceptor; process memory only; dropped on +stop+.
+  #
+  # Ruby idiom (as Python): the manifest is refreshed LAZILY at the TTL — the
+  # first request after +ttl_seconds+ pays one management call — rather than
+  # by a background thread. Behaviourally the same contract ("hold the manifest
+  # for ttl_seconds, then refresh"), and it works identically under Puma
+  # threads, a forked Unicorn/Sidekiq worker and a plain script, with no
+  # thread to own.
+  #
+  # - single-flight: concurrent refreshes share one fetch (a caller that waited
+  #   on the mutex while another refreshed takes that answer);
+  # - stale-but-valid: a failed refresh keeps the last GOOD manifest and backs
+  #   off exponentially from the second consecutive failure (cap 8×TTL);
+  # - a 401/403/404 from the manifest endpoint — the credential lacks
+  #   routes:read, or an older server — is NOT a routing failure: the store
+  #   warns once, behaves as "no manifest" (every listed host stays on the
+  #   ephemeral path exactly as before this feature), and re-checks at 10×TTL;
+  # - out-of-cycle refreshes (a route-mode refusal, a promoted-route hint, an
+  #   explicit +refresh+) are rate-limited so a burst costs one call.
+  #
+  # Discovery failing open is deliberate and bounded: it can only leave a host
+  # on the path it was on before the manifest existed. The DATA-PLANE hop is
+  # where fail-closed lives (D4), and that is in the intercept pipeline.
+  class InterceptManifestStore
+    DEFAULT_TTL_SECONDS = 60
+    MAX_BACKOFF_FACTOR = 8
+    PERMISSION_RECHECK_FACTOR = 10
+    MONOTONIC = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+    attr_reader :manifest, :version, :last_error
+    # Seconds between out-of-cycle refreshes (a refusal, a hint, an explicit
+    # refresh); a burst inside the gap costs one call.
+    attr_accessor :min_refresh_gap
+
+    # @param fetch [#call] performs GET /v1/wrap/intercept-manifest and returns the Hash.
+    #   When it accepts an +if_none_match:+ keyword the store passes the version it
+    #   holds on every poll after the first (+If-None-Match: W/"<version>"+ on the
+    #   wire) and reads +nil+ as the server's 304: keep the manifest, restart the
+    #   TTL clock, fire no +on_refresh+ (PARITY §21.1 "Conditional poll"). A
+    #   zero-argument callable is accepted and simply polls unconditionally.
+    # @param on_refresh [#call, nil] receives {reason:, version:, added:, removed:} after a change
+    # @param on_error [#call, nil] receives the exception of a failed refresh
+    # @param min_refresh_gap [Numeric] seconds between out-of-cycle refreshes
+    # @param now [#call] the clock (monotonic seconds); a test seam
+    def initialize(fetch, on_refresh: nil, on_error: nil, min_refresh_gap: 5.0, now: MONOTONIC)
+      @fetch = fetch
+      @fetch_conditional = self.class.accepts_if_none_match?(fetch)
+      @on_refresh = on_refresh
+      @on_error = on_error
+      @min_refresh_gap = min_refresh_gap
+      @now = now
+      @manifest = nil
+      @version = nil
+      @expires_at = 0.0 # stale until the first refresh
+      @last_refresh_at = -1e9
+      @failures = 0
+      @permission_denied = false
+      @last_error = nil
+      @stopped = false
+      @seq = 0
+      @mutex = Mutex.new
+    end
+
+    def permission_denied? = @permission_denied
+    def stopped? = @stopped
+
+    # Whether +fetch+ can take +if_none_match:+ (a keyword, or **rest). Decided
+    # once at construction so a zero-argument test/user seam keeps working.
+    def self.accepts_if_none_match?(fetch)
+      return false unless fetch.respond_to?(:parameters)
+
+      fetch.parameters.any? do |kind, name|
+        (%i[key keyreq].include?(kind) && name == :if_none_match) || kind == :keyrest
+      end
+    end
+
+    # Whether the next request should refresh before deciding.
+    def stale?
+      !@stopped && @now.call >= @expires_at
+    end
+
+    # A promoted-route hint arrived: make the NEXT request refresh (rate-limited).
+    def hint
+      @mutex.synchronize { @expires_at = @now.call if @now.call - @last_refresh_at >= @min_refresh_gap }
+    end
+
+    # Drop the manifest and refuse further refreshes.
+    def stop
+      @mutex.synchronize do
+        @stopped = true
+        @manifest = nil
+        @version = nil
+      end
+    end
+
+    # Refresh if stale (first load, TTL expiry, a hint), then return the manifest.
+    def ensure
+      refresh("ttl", force: true) if stale?
+      @manifest
+    end
+
+    # Refresh now. Single-flight; rate-limited unless +force+. Returns the
+    # manifest the store holds afterwards (nil after a permission refusal).
+    # Never raises for a fetch failure — the store has already applied
+    # stale-keep / backoff; read +last_error+.
+    def refresh(reason, force: false)
+      return nil if @stopped
+
+      seq_before = @seq # bumped when an attempt COMPLETES
+      @mutex.synchronize do
+        return nil if @stopped
+        # An attempt completed while we waited on the mutex: take its answer
+        # (single-flight — the refresh we queued behind is the one we wanted).
+        return @manifest if @seq != seq_before
+        return @manifest if !force && @now.call - @last_refresh_at < @min_refresh_gap
+
+        do_refresh(reason)
+      end
+    end
+
+    private
+
+    # Runs under @mutex. Hooks are invoked inside the lock deliberately kept
+    # cheap; a hook must not call back into the store.
+    def do_refresh(reason)
+      @last_refresh_at = @now.call
+      begin
+        # Every poll after the first is conditional on the held version; the
+        # server answers 304 (→ nil) when nothing changed, and that is a
+        # success: keep the manifest, restart the TTL clock, fire no hook.
+        nxt = @fetch_conditional && @version ? @fetch.call(if_none_match: @version) : @fetch.call
+      rescue StandardError => e
+        @seq += 1 # this attempt is over: a waiter that queued behind it takes its answer
+        @last_error = e
+        @on_error&.call(e)
+        status = e.is_a?(APIError) ? e.status_code : nil
+        if [401, 403, 404].include?(status)
+          # Not a routing failure: the credential cannot read routes, or the
+          # server predates the manifest. Every listed host stays ephemeral,
+          # as it was before this feature existed. Warn once, re-check slowly.
+          @permission_denied = true
+          @manifest = nil
+          @version = nil
+          Warnings.warn_once(
+            "KNOXCALL_INTERCEPT_MANIFEST_UNAVAILABLE",
+            "KnoxCall intercept manifest unavailable (HTTP #{status}): route-aware interception is off " \
+            "for this client — listed hosts use the ephemeral proxy. Grant the credential `routes:read` " \
+            "(or upgrade the server) to enable it."
+          )
+          @expires_at = @now.call + DEFAULT_TTL_SECONDS * PERMISSION_RECHECK_FACTOR
+        else
+          # Transport or server fault: keep the last good manifest, back off
+          # from the second consecutive failure.
+          @failures = [@failures + 1, 30].min
+          factor = [2**(@failures - 1), MAX_BACKOFF_FACTOR].min
+          base = ttl_of(@manifest)
+          @expires_at = @now.call + [base * factor, base * MAX_BACKOFF_FACTOR].min
+        end
+        return @manifest
+      end
+
+      @seq += 1
+      prev = @manifest
+      @failures = 0
+      @permission_denied = false
+      @last_error = nil
+      if nxt.nil?
+        # Not modified: the held manifest stands for another TTL.
+        @expires_at = @now.call + ttl_of(prev)
+        return @manifest
+      end
+      version = nxt["version"].to_s
+      if prev.nil? || @version != version
+        before = (prev ? prev["routes"] : []).to_h { |e| [entry_key(e), e] }
+        after = (nxt["routes"] || []).to_h { |e| [entry_key(e), e] }
+        added = after.reject { |k, _| before.key?(k) }.values
+        removed = before.reject { |k, _| after.key?(k) }.values
+        @manifest = nxt
+        @version = version
+        if @on_refresh && (!added.empty? || !removed.empty? || prev.nil?)
+          @on_refresh.call(reason: reason, version: version, added: added, removed: removed)
+        end
+      end
+      @expires_at = @now.call + ttl_of(nxt)
+      @manifest
+    end
+
+    def ttl_of(manifest)
+      ttl = manifest && manifest["ttl_seconds"]
+      ttl.is_a?(Numeric) && ttl.positive? ? ttl.to_f : DEFAULT_TTL_SECONDS.to_f
+    end
+
+    def entry_key(e)
+      [e["host"], e["base_path"], e["slug"]]
+    end
+  end
+end

data/lib/knoxcall/login.rb

@@ -0,0 +1,144 @@
+require "rbconfig"
+require "knoxcall/cli/common"
+require "knoxcall/cli/login"
+
+module KnoxCall
+  # Interactive first-run authentication — OPT-IN, and NEVER on the request
+  # path (PARITY §14).
+  #
+  # The persistent credential (`knoxcall login` -> ~/.knoxcall/credentials.json,
+  # rotating refresh token) already survives restarts; these helpers just let
+  # the SDK *initiate* that login programmatically. Because an SDK is embedded
+  # in someone else's process (production servers, CI, background jobs), a
+  # browser/device flow must be an explicit, TTY-gated call — never a silent
+  # side effect of a normal API call. Client construction and #call never
+  # trigger this; they raise NotAuthenticatedError when no credential is found.
+  #
+  #   client = KnoxCall.ensure_login              # reuse a stored profile, else prompt once
+  #   client = KnoxCall.login(mode: "device")     # force a fresh interactive login
+  #
+  # They reuse the already-tested CLI auth-code+PKCE loopback / RFC 8628 device
+  # flow (KnoxCall::CLI::Login) and its persist helper (KnoxCall::CLI::Common),
+  # so there is exactly one implementation of each flow.
+  class << self
+    # Run the interactive browser (loopback) or device-code login, persist the
+    # credential to ~/.knoxcall/credentials.json, and return a ready client
+    # bound to the written profile.
+    #
+    # @param tenant [String, nil] tenant hint for the authorize URL (optional;
+    #   discovered otherwise)
+    # @param sandbox [Boolean] target the sandbox host / Test data plane
+    # @param base_url [String, nil] management base URL override
+    #   (default production/sandbox, or KNOXCALL_BASE_URL)
+    # @param profile [String, nil] credentials-file profile to write/read
+    #   (default: KNOXCALL_PROFILE or "default")
+    # @param mode ["auto", "browser", "device"] "auto" opens a browser on a
+    #   desktop TTY, else falls back to the device flow
+    # @param timeout [Numeric] loopback wait timeout for the browser flow (s)
+    # @param allow_non_interactive [Boolean] bypass the TTY / CI /
+    #   KNOXCALL_NO_INTERACTIVE guard (default false)
+    # @param open_browser [#call, nil] custom browser launcher (defaults to the
+    #   OS opener) — receives the authorize URL
+    # @param client_options [Hash] extra options forwarded to the returned
+    #   KnoxCall::Client (symbol keys)
+    # @return [KnoxCall::Client] a client bound to the freshly-written profile
+    # @raise [NotAuthenticatedError] when prompting is unsafe (no TTY, CI, or
+    #   KNOXCALL_NO_INTERACTIVE) and allow_non_interactive is not set
+    def login(tenant: nil, sandbox: false, base_url: nil, profile: nil,
+              mode: "auto", timeout: 300.0, allow_non_interactive: false,
+              open_browser: nil, client_options: {})
+      mode = mode.to_s
+      unless %w[auto browser device].include?(mode)
+        raise ArgumentError, %(mode must be "auto", "browser", or "device" (got #{mode.inspect}))
+      end
+      interactive_guard(allow_non_interactive)
+
+      resolved_base = (base_url || CLI::Common.default_base_url(sandbox)).chomp("/")
+      resolved_profile = CredentialsFile.resolve_profile(profile)
+      use_device = mode == "device" || (mode == "auto" && !desktop_browser?)
+
+      token_body =
+        if use_device
+          CLI::Login.device_flow(resolved_base)
+        else
+          CLI::Login.auth_code_flow(resolved_base, tenant: tenant,
+                                                   open_browser: open_browser, timeout: timeout)
+        end
+
+      CLI::Common.persist_login(
+        path: CredentialsFile.resolve_path,
+        profile: resolved_profile,
+        base_url: resolved_base,
+        token_body: token_body,
+        fallback_tenant: tenant
+      )
+      client_from_profile(resolved_profile, sandbox, client_options)
+    end
+
+    # Return a client from an already-stored credential for the profile when one
+    # is present (no prompt, no network), otherwise run the interactive {#login}
+    # once. The ergonomic "make sure I'm authenticated, then give me a client"
+    # entry point. Accepts the same options as {#login}.
+    #
+    # @return [KnoxCall::Client]
+    def ensure_login(tenant: nil, sandbox: false, base_url: nil, profile: nil,
+                     mode: "auto", timeout: 300.0, allow_non_interactive: false,
+                     open_browser: nil, client_options: {})
+      resolved_profile = CredentialsFile.resolve_profile(profile)
+      if CredentialsFile.profile_available?(CredentialsFile.resolve_path, resolved_profile)
+        return client_from_profile(resolved_profile, sandbox, client_options)
+      end
+      login(tenant: tenant, sandbox: sandbox, base_url: base_url, profile: profile,
+            mode: mode, timeout: timeout, allow_non_interactive: allow_non_interactive,
+            open_browser: open_browser, client_options: client_options)
+    end
+
+    private
+
+    # Refuse to pop a browser or block on a device code where doing so is
+    # unsafe: a non-interactive process (no TTY), CI, or an explicit opt-out.
+    # The caller can override with allow_non_interactive when they know it is
+    # safe (PARITY §14).
+    def interactive_guard(allow_non_interactive)
+      return if allow_non_interactive
+      if env_set?("KNOXCALL_NO_INTERACTIVE") || env_set?("CI")
+        raise NotAuthenticatedError,
+              "interactive login is disabled here (KNOXCALL_NO_INTERACTIVE or CI is set). " \
+              "Provision a non-interactive credential (client_id/secret or workload OIDC) instead."
+      end
+      unless $stdin.tty? && $stdout.tty?
+        raise NotAuthenticatedError,
+              "no interactive terminal detected — run `knoxcall login` in a terminal, " \
+              "or provision a non-interactive credential (client_id/secret or workload OIDC)."
+      end
+    end
+
+    # A present, non-empty env var counts as "set" — mirrors node's
+    # truthy-string test (so CI=false still counts as CI being present).
+    def env_set?(name)
+      value = ENV[name]
+      !value.nil? && !value.empty?
+    end
+
+    # Headless CI is already blocked by interactive_guard, so this only chooses
+    # browser-vs-device on a real TTY. On Linux, require a display server.
+    def desktop_browser?
+      if RbConfig::CONFIG["host_os"] =~ /linux/
+        env_set?("DISPLAY") || env_set?("WAYLAND_DISPLAY")
+      else
+        true
+      end
+    end
+
+    # Build a client bound to a stored profile. Construction performs no network
+    # I/O; the StoredCredentials bootstrap seeds tenant/base_url from the file
+    # (unless overridden) and refreshes tokens under the file lock at first use.
+    def client_from_profile(profile, sandbox, client_options)
+      opts = (client_options || {}).merge(
+        bootstrap: StoredCredentials.new(profile: profile),
+        sandbox: sandbox
+      )
+      Client.new(opts)
+    end
+  end
+end

data/lib/knoxcall/resources/account.rb

@@ -0,0 +1,12 @@
+module KnoxCall
+  module Resources
+    class Account
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      def get = unwrap(@client.request("GET", "/v1/account"))
+      def get_usage = unwrap(@client.request("GET", "/v1/account/usage"))
+    end
+  end
+end

data/lib/knoxcall/resources/agents.rb

@@ -0,0 +1,25 @@
+module KnoxCall
+  module Resources
+    class Agents
+      include UnwrapsEnvelope
+
+      def initialize(client) = @client = client
+
+      # Bare array — no pagination.
+      def list = unwrap(@client.request("GET", "/v1/agents"))
+      # The response's "agent_secret" is shown exactly once — store it now.
+      # (The server hand-rolls this 201: data carries the secret, meta only
+      # {secret_shown_once: true} — unwrapping still applies.)
+      # Requires an explicit `agent:create` policy grant: a wildcard (`*:*`) rule
+      # does not satisfy it, including the `legacy_admin` policy every key created
+      # before 2026-06-30 still carries. The seeded Key - Infrastructure and Key -
+      # Editor roles name the action literally and are unaffected. Without it the
+      # call returns 403. Every successful mint also emails the account's owners.
+      def create(name) = unwrap(@client.request("POST", "/v1/agents", body: { name: name }))
+      # Returns {"revoked" => true}.
+      def revoke(agent_id) = unwrap(@client.request("DELETE", "/v1/agents/#{encode(agent_id)}"))
+      # Bare array (server-capped at 50 rows) — no pagination.
+      def get_tamper_events(agent_id) = unwrap(@client.request("GET", "/v1/agents/#{encode(agent_id)}/tamper-events"))
+    end
+  end
+end