ruby-utcp 1.1.4 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 265426eb4dd2ca952c81a23b71aeb8c1f0b1c90f8fbf247ec502279b0129ffba
-  data.tar.gz: 79c0d4d21648777686b7caf3cc32f333cb7001bfcf8fa3f10c340195a706f449
+  metadata.gz: 8e5c4728819e312335ad446c2b453ceb45eafc6440d7926fd4116fac91852d4f
+  data.tar.gz: 5902911212d47fe254285b3218e7b47338bedef182ec1561b5b778de8c354d99
 SHA512:
-  metadata.gz: 698ae3e9f0600fedeaa7adf2ae51c4e6872affed4a2da34454456c51f444a25d83ae59d6984d395b77f85ca36fa426731bcca6565cd0e7b1fc915473cb1caf3a
-  data.tar.gz: 1a0ff70255dbd8b4ab2b7b323e638d726646423833144eed365d3fd9236908a038e0652c18548e9095ecbbfa87a87b2d01b5167dc8d93125918b09054326f21d
+  metadata.gz: 6631d90cb34d055462da1f31105380e5d61ba0b7bb73aaaf7494e5a7c5f826258e76b8cbb84bb7263ad73641866592e248fd94d47ef64d6b7ba4f7e0ed302a25
+  data.tar.gz: 56f38514be76d1e9dd0565084e7c1d6febfed61dc45f1a3ff27b9ff6849827b8bb184c255e2ef8b5e8d273015890af70ec006a8280eb4dc8cf4b3c8f5571f49b

data/README.md

@@ -125,6 +125,29 @@ Complete runnable/configuration examples are in [examples/README.md](examples/RE
 
 Run `make` to start every available matching local server, execute its clients, and cleanly stop the servers. Missing optional gRPC/WebRTC backends are reported and skipped. `make full-demo` is the strict 12/12 target; `make standard-demo` always runs only the pairs that do not need native backends.
 
+### Authentication by transport
+
+| Transport | Supported `auth` | Authentication checks |
+| --- | --- | --- |
+| HTTP | API key in header/query/cookie, Basic, OAuth2 | Discovery and calls; strips credentials on cross-origin redirects |
+| SSE | API key in header/query/cookie, Basic, OAuth2 | Discovery and streaming; streaming redirects are rejected |
+| Streamable HTTP (`streamable_http`, alias `http_stream`) | API key in header/query/cookie, Basic, OAuth2 | Discovery and streaming; streaming redirects are rejected |
+| WebSocket | API key in header/query/cookie, Basic, OAuth2 | Handshake; connections are separated by client and effective credentials |
+| GraphQL | API key in header/query/cookie, Basic, OAuth2 | Introspection, queries/mutations and WebSocket subscriptions |
+| gRPC | API key with `location: "header"` mapped to metadata, Basic, OAuth2 | Discovery, unary calls and server streams |
+| MCP HTTP | API key in header/query/cookie, Basic, OAuth2 | Initialization, discovery and calls; sessions are separated by client, endpoint and credentials |
+| MCP stdio | No built-in `auth` support | Rejects `auth` before starting a process; configure the server's own credentials through its environment |
+| CLI | No built-in `auth` support | Rejects `auth`; the invoked command can use explicit `env_vars` |
+| TCP | No built-in `auth` support | Rejects `auth` before socket I/O; application message authentication is caller-defined |
+| UDP | No built-in `auth` support | Rejects `auth` before socket I/O; application message authentication is caller-defined |
+| WebRTC | No built-in `auth` support | Rejects `auth` before creating a peer; signaling authentication is not implemented |
+| Text | No transport `auth` | Rejects `auth`; `auth_tools` can configure tools converted from OpenAPI |
+| File | No transport `auth` | Rejects `auth` before reading a file; `auth_tools` can configure tools converted from OpenAPI |
+
+Unsupported auth configuration raises `AuthenticationError` on calls and makes manual registration fail. HTTP/WebSocket 401/403 and native gRPC UNAUTHENTICATED/PERMISSION_DENIED errors are reported as `AuthenticationError`. Invalid header/cookie API keys containing CR/LF are rejected before transport I/O. MCP session IDs are stripped on cross-origin redirects; changed auth or static server headers create a fresh, initialized session. Custom MCP session factories are responsible for their own authentication.
+
+The default suite tests the auth matrix at transport boundaries and uses local HTTP/WebSocket servers for wire-level checks. Native gRPC checks additionally run with `UTCP_NATIVE_TESTS=1 bundle exec rake native TESTOPTS='--name /NativeGRPCTest/'`; this subset does not require loading the WebRTC backend.
+
 ### HTTP, SSE, and Streamable HTTP
 
 HTTP templates support URL path parameters, query parameters, JSON or text bodies, input-to-header mapping, API keys, Basic auth, and OAuth2 client credentials.
@@ -147,6 +170,8 @@ HTTP templates support URL path parameters, query parameters, JSON or text bodie
 
 Remote HTTP endpoints must use HTTPS. Plain HTTP is accepted only for loopback hosts, which keeps local development convenient. Redirect targets are checked again and credentials are removed on cross-origin redirects.
 
+Cross-origin redirects remove explicit `Authorization`, `Proxy-Authorization`, and `Cookie` headers as well as headers supplied by the auth configuration. OAuth2 token requests follow redirects only within the same origin (scheme, host, and port), so client credentials cannot be forwarded to another origin. Cached OAuth2 tokens are keyed by the token URL, client ID, client secret, and scope; changing credentials requires a new token request.
+
 An HTTP, text, or file manual may also contain an OpenAPI 3 or Swagger 2 document. It is converted into UTCP tools automatically.
 
 SSE and Streamable HTTP reuse the same URL, header, body, and auth conventions. Their streaming forms expose ordinary Ruby enumerators:

data/lib/utcp/protocols/base.rb

@@ -24,6 +24,12 @@ module UTCP
 
     private
 
+    def assert_no_auth!(template, context: template.call_template_type)
+      return unless template.auth
+
+      raise AuthenticationError, "#{context} does not support the auth field"
+    end
+
     def manual_from_payload(template, payload, source: "protocol response")
       data = if payload.is_a?(String)
                Utils.parse_document(payload, source: source)

data/lib/utcp/protocols/cli.rb

@@ -43,9 +43,9 @@ module UTCP
     private
 
     def assert_template!(template)
-      return if template.is_a?(CliCallTemplate)
+      raise ValidationError, "CLI protocol requires a CliCallTemplate" unless template.is_a?(CliCallTemplate)
 
-      raise ValidationError, "CLI protocol requires a CliCallTemplate"
+      assert_no_auth!(template)
     end
 
     def execute(client, template, arguments)
@@ -183,4 +183,3 @@ module UTCP
   end
   CliCommunicationProtocol = CLIProtocol
 end
-

data/lib/utcp/protocols/file.rb

@@ -34,9 +34,9 @@ module UTCP
     private
 
     def assert_template!(template)
-      return if template.is_a?(FileCallTemplate)
+      raise ValidationError, "file protocol requires a FileCallTemplate" unless template.is_a?(FileCallTemplate)
 
-      raise ValidationError, "file protocol requires a FileCallTemplate"
+      assert_no_auth!(template)
     end
 
     def resolve_path(client, path)
@@ -49,4 +49,3 @@ module UTCP
   end
   FileCommunicationProtocol = FileProtocol
 end
-

data/lib/utcp/protocols/grpc.rb

@@ -85,15 +85,21 @@ module UTCP
         deadline: Time.now + timeout,
         metadata: metadata
       )
+    rescue GRPC::Unauthenticated, GRPC::PermissionDenied => error
+      raise AuthenticationError, "gRPC authentication failed: #{error.details}"
     end
 
     def server_stream(route, payload, timeout:, metadata: {})
+      return enum_for(__method__, route, payload, timeout: timeout, metadata: metadata) unless block_given?
+
       @stub.server_streamer(
         route, payload,
         ->(value) { value.to_s.b }, ->(bytes) { bytes },
         deadline: Time.now + timeout,
         metadata: metadata
-      )
+      ).each { |response| yield response }
+    rescue GRPC::Unauthenticated, GRPC::PermissionDenied => error
+      raise AuthenticationError, "gRPC authentication failed: #{error.details}"
     end
   end
 
@@ -165,9 +171,20 @@ module UTCP
     private
 
     def assert_grpc_template!(template)
-      return if template.is_a?(GrpcCallTemplate)
+      raise ValidationError, "gRPC protocol requires a GrpcCallTemplate" unless template.is_a?(GrpcCallTemplate)
 
-      raise ValidationError, "gRPC protocol requires a GrpcCallTemplate"
+      case template.auth
+      when nil, BasicAuth, OAuth2Auth
+        nil
+      when ApiKeyAuth
+        unless template.auth.location == "header"
+          raise AuthenticationError, "gRPC API keys require location=header (request metadata)"
+        end
+        assert_header_safe!(template.auth.var_name, "API key name")
+        assert_header_safe!(template.auth.api_key, "API key value")
+      else
+        raise AuthenticationError, "Unsupported gRPC authentication type: #{template.auth.auth_type}"
+      end
     end
 
     def rpc_client(template)

data/lib/utcp/protocols/http.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "base64"
+require "digest/sha2"
 require "ipaddr"
 require "json"
 require "net/http"
@@ -41,6 +42,7 @@ module UTCP
 
   class HTTPProtocol < CommunicationProtocol
     REDIRECTS = [301, 302, 303, 307, 308].freeze
+    SENSITIVE_HEADERS = %w[Authorization Proxy-Authorization Cookie].freeze
     REQUEST_CLASSES = {
       "GET" => Net::HTTP::Get,
       "POST" => Net::HTTP::Post,
@@ -183,6 +185,7 @@ module UTCP
       case auth
       when ApiKeyAuth
         assert_header_safe!(auth.var_name, "API key name")
+        assert_header_safe!(auth.api_key, "API key value") unless auth.location == "query"
         case auth.location
         when "header"
           headers[auth.var_name] = auth.api_key
@@ -207,7 +210,10 @@ module UTCP
 
     def oauth_token(auth)
       @oauth_mutex.synchronize do
-        cache_key = [auth.token_url, auth.client_id, auth.scope]
+        # Include the full credentials without retaining a plaintext secret in the cache key.
+        cache_key = Digest::SHA256.hexdigest(JSON.generate([
+          auth.token_url, auth.client_id, auth.client_secret, auth.scope
+        ]))
         cached = @oauth_tokens[cache_key]
         return cached[:token] if cached && cached[:expires_at] > Time.now.to_f + 5
 
@@ -222,7 +228,7 @@ module UTCP
           "POST", token_uri,
           headers: {}, cookies: {}, body: URI.encode_www_form(fields),
           content_type: "application/x-www-form-urlencoded", timeout: @open_timeout,
-          sensitive_headers: ["Authorization"]
+          sensitive_headers: ["Authorization"], allow_cross_origin_redirects: false
         )
         data = JSON.parse(response.body)
         token = data["access_token"]
@@ -239,7 +245,7 @@ module UTCP
     end
 
     def perform_request(method, uri, headers:, cookies:, body:, content_type:, timeout:,
-                        sensitive_headers:, redirects: 0)
+                        sensitive_headers:, redirects: 0, allow_cross_origin_redirects: true)
       URLSecurity.validate!(uri.to_s, context: "HTTP request")
       raise ToolCallError, "Too many HTTP redirects" if redirects > @max_redirects
 
@@ -271,7 +277,13 @@ module UTCP
         next_headers = headers.dup
         next_cookies = cookies.dup
         unless URLSecurity.same_origin?(uri, target)
-          sensitive_headers.each { |name| next_headers.delete_if { |key, _| key.casecmp?(name) } }
+          # Token requests carry credentials in the body, which header stripping cannot protect.
+          unless allow_cross_origin_redirects
+            raise SecurityError, "Cross-origin HTTP redirects are not allowed for this request"
+          end
+          (SENSITIVE_HEADERS + sensitive_headers).each do |name|
+            next_headers.delete_if { |key, _| key.casecmp?(name) }
+          end
           next_cookies = {}
         end
         next_method = response.code.to_i == 303 || ([301, 302].include?(response.code.to_i) && method.to_s.upcase == "POST") ? "GET" : method
@@ -279,7 +291,8 @@ module UTCP
         return perform_request(
           next_method, target, headers: next_headers, cookies: next_cookies,
           body: next_body, content_type: content_type, timeout: timeout,
-          sensitive_headers: sensitive_headers, redirects: redirects + 1
+          sensitive_headers: sensitive_headers, redirects: redirects + 1,
+          allow_cross_origin_redirects: allow_cross_origin_redirects
         )
       end
 

data/lib/utcp/protocols/mcp.rb

@@ -232,7 +232,6 @@ module UTCP
       template.servers.each do |server_name, config|
         begin
           session = session_for(client, template, server_name, config)
-          initialize_session(session, template)
           each_list_item(session, "tools/list", "tools") do |tool|
             tools << Tool.new(
               name: "#{server_name}.#{tool.fetch("name")}",
@@ -296,6 +295,7 @@ module UTCP
       query = {}
       cookies = {}
       sensitive = apply_auth(template.auth, headers, query, cookies)
+      sensitive << "MCP-Session-Id"
       if template.auth.is_a?(OAuth2Auth)
         headers["Authorization"] = "Bearer #{oauth_token(template.auth)}"
         sensitive << "Authorization"
@@ -326,15 +326,32 @@ module UTCP
     end
 
     def session_for(client, template, server_name, config)
-      key = [client, template.name, server_name]
+      http_transport = %w[http streamable_http sse].include?(config["transport"].to_s) || config["url"]
+      assert_no_auth!(template, context: "MCP stdio") unless http_transport || @session_factory
+      # A session belongs to the credentials and endpoint used to initialize it.
+      fingerprint = Digest::SHA256.hexdigest(JSON.generate([
+        config, template.auth&.to_h, template.protocol_version, template.timeout
+      ]))
+      key = [client, template.name, server_name, fingerprint]
       @sessions_mutex.synchronize do
-        @sessions[key] ||= if @session_factory
-                            @session_factory.call(server_name, config, template)
-                          elsif %w[http streamable_http sse].include?(config["transport"].to_s) || config["url"]
-                            MCPHTTPSession.new(config, template, self)
-                          else
-                            MCPStdioSession.new(config, template.timeout)
-                          end
+        return @sessions[key] if @sessions.key?(key)
+
+        snapshot = McpCallTemplate.from_h(Utils.deep_copy(template.to_h))
+        server_config = snapshot.servers.fetch(server_name)
+        session = if @session_factory
+                    @session_factory.call(server_name, server_config, snapshot)
+                  elsif http_transport
+                    MCPHTTPSession.new(server_config, snapshot, self)
+                  else
+                    MCPStdioSession.new(server_config, snapshot.timeout)
+                  end
+        begin
+          initialize_session(session, snapshot)
+        rescue StandardError
+          session.close
+          raise
+        end
+        @sessions[key] = session
       end
     end
 

data/lib/utcp/protocols/tcp.rb

@@ -31,9 +31,9 @@ module UTCP
     private
 
     def assert_template!(template)
-      return if template.is_a?(TcpCallTemplate)
+      raise ValidationError, "TCP protocol requires a TcpCallTemplate" unless template.is_a?(TcpCallTemplate)
 
-      raise ValidationError, "TCP protocol requires a TcpCallTemplate"
+      assert_no_auth!(template)
     end
 
     def exchange(template, message)

data/lib/utcp/protocols/text.rb

@@ -30,9 +30,9 @@ module UTCP
     private
 
     def assert_template!(template)
-      return if template.is_a?(TextCallTemplate)
+      raise ValidationError, "text protocol requires a TextCallTemplate" unless template.is_a?(TextCallTemplate)
 
-      raise ValidationError, "text protocol requires a TextCallTemplate"
+      assert_no_auth!(template)
     end
 
     def openapi?(data)
@@ -41,4 +41,3 @@ module UTCP
   end
   TextCommunicationProtocol = TextProtocol
 end
-

data/lib/utcp/protocols/udp.rb

@@ -30,9 +30,9 @@ module UTCP
     private
 
     def assert_template!(template)
-      return if template.is_a?(UdpCallTemplate)
+      raise ValidationError, "UDP protocol requires a UdpCallTemplate" unless template.is_a?(UdpCallTemplate)
 
-      raise ValidationError, "UDP protocol requires a UdpCallTemplate"
+      assert_no_auth!(template)
     end
 
     def exchange(template, message, response_count:)

data/lib/utcp/protocols/webrtc.rb

@@ -204,9 +204,9 @@ module UTCP
     private
 
     def assert_webrtc_template!(template)
-      return if template.is_a?(WebRtcCallTemplate)
+      raise ValidationError, "WebRTC protocol requires a WebRtcCallTemplate" unless template.is_a?(WebRtcCallTemplate)
 
-      raise ValidationError, "WebRTC protocol requires a WebRtcCallTemplate"
+      assert_no_auth!(template)
     end
 
     def peer_for(client, template)

data/lib/utcp/protocols/websocket.rb

@@ -140,6 +140,9 @@ module UTCP
       header_text = read_headers
       lines = header_text.split("\r\n")
       status = lines.shift.to_s.split[1].to_i
+      if status == 401 || status == 403
+        raise AuthenticationError, "WebSocket authentication failed with status #{status}"
+      end
       raise ToolCallError, "WebSocket handshake failed with status #{status}" unless status == 101
 
       response_headers = lines.each_with_object({}) do |line, result|

data/lib/utcp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module UTCP
-  VERSION = "1.1.4"
+  VERSION = "1.1.5"
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-utcp
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.1.5
 platform: ruby
 authors:
 - ruby-utcp contributors