datagrout-conduit 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 177af76b0cdd7d7e82fd1384db89da6a5dd4b3152ff5f07e255075dec041a91c
-  data.tar.gz: 34b1c4d17471013349db85beb09f167719e4fc0189204b117042c1394fc175f8
+  metadata.gz: c586cb9aae6cf748677d41c1b453bc4ed896e440b68d43451a50c5ed3333282d
+  data.tar.gz: bda496e4dc74051928c73115e6c69a23515e3b930ba82ccbe5bfedd12131e00b
 SHA512:
-  metadata.gz: 6812db873347c88a86bfd0ecce380e6d264b4f66854d3eeb01e3ee4a28b89cf2b6e8f93423442ea9b0c14fcb40c68cd6bcc2d6210a5f343200115dd92343ff35
-  data.tar.gz: 23deaeee4cfe9be72cc546b919e5a87cb5ea5fa108831c346a4e02b0faa501578b582632f538a42dd0456095a9b8589511e349318c95f414b086bed7a0d90980
+  metadata.gz: 856a644371b034af39a9e6caf6ea15ff6c088c0d504c0ef22094f35f70f46eadf7bf6ed85967a14484872f7a8d49f1e2064400d34325c8700032dfbb3d45f134
+  data.tar.gz: 4f34ee08b4d4e126bde2a8b053ec2f9443ae31f1b1aa332eac6649d88944a736a3f31f6ac87880a685f246a4a68fab56c1bb86f720fa1e0adb5df6d08b2d48df

data/README.md

@@ -9,13 +9,13 @@ Connect to remote MCP and JSONRPC servers, invoke tools, discover capabilities w
 Add to your Gemfile:
 
 ```ruby
-gem "datagrout-conduit", "~> 0.5.0"
+gem "datagrout-conduit", "~> 0.8.0"
 ```
 
 Or install directly:
 
 ```sh
-gem install datagrout-conduit -v 0.5.0
+gem install datagrout-conduit -v 0.8.0
 ```
 
 ## Quick Start
@@ -81,6 +81,106 @@ client = DatagroutConduit::Client.new(
 
 The token endpoint is auto-derived from MCP URLs — `/mcp` becomes `/oauth/token`. Tokens are cached and refreshed 60 seconds before expiry.
 
+### OAuth 2.1 (authorization code + PKCE)
+
+Client credentials authenticate a *machine*, with a secret issued out of band.
+To authenticate a *person* — and to reach
+`https://gateway.datagrout.ai/connect`, where the server binding is chosen at
+consent time and lives in the token rather than the URL — run the
+browser-consent flow once and persist the grant:
+
+```ruby
+AC = DatagroutConduit::AuthCode
+
+listener = AC::LoopbackListener.bind           # 127.0.0.1, OS-chosen port
+flow = AC::Flow.discover("https://gateway.datagrout.ai/connect")
+registered = flow.register("My App", listener.redirect_uri)
+
+url, pending = flow.authorize_url
+puts "Open this to sign in:\n#{url}"           # the SDK never opens a browser
+
+redirect = listener.wait(timeout: 300)
+grant = flow.exchange(pending, redirect.code, redirect.state)
+
+# Persist BOTH: a client id without its redirect URI cannot be reused, because
+# the authorization server matches redirect URIs exactly.
+save_somewhere(registered: registered.to_h, grant: grant.to_h)
+```
+
+On later runs, skip straight to the grant:
+
+```ruby
+client = DatagroutConduit::Client.new(
+  url: "https://gateway.datagrout.ai/connect",
+  auth: { authorization_code: grant }
+)
+```
+
+DataGrout **rotates refresh tokens**, so a grant that is refreshed and not
+written back leaves a consumed token on disk. Own the provider when you care:
+
+```ruby
+provider = AC::Provider.new(grant)
+client = DatagroutConduit::Client.new(url: url, auth: { authorization_code: provider })
+
+# ...periodically, or once on shutdown:
+rotated = provider.take_if_dirty
+save_somewhere(registered: registered.to_h, grant: rotated.to_h) if rotated
+```
+
+Where the grant lives is your decision — a keychain, a config file, a vault.
+The SDK owns its shape and its refresh, and deliberately picks no location. The
+shape is identical across every conduit SDK, so a grant written by the Python
+client is readable by this one.
+
+See [`examples/browser_signin.rb`](examples/browser_signin.rb) for a complete
+run that registers, signs in, saves, and reuses.
+
+### Delegation (RFC 8693 — an agent acting for a user)
+
+Client credentials say *which machine* is calling; authorization code says
+*which person* consented. An agent working on a user's behalf needs both, so
+the resource server can audit, rate-limit and revoke the agent separately from
+the user. An RFC 8693 exchange produces that token from two you already have:
+
+```ruby
+D = DatagroutConduit::Delegation
+
+# The agent's own credential — the actor.
+agent = DatagroutConduit::OAuth::TokenProvider.new(
+  client_id: "agent_client_id",
+  client_secret: "agent_client_secret",
+  token_endpoint: "https://gateway.datagrout.ai/oauth/token"
+)
+
+request = D::Request.new(
+  token_endpoint: "https://gateway.datagrout.ai/oauth/token",
+  client_id: "agent_client_id",
+  client_secret: "agent_client_secret",
+  resource: "https://gateway.datagrout.ai/connect"
+)
+
+provider = D::Provider.new(
+  request,
+  # The user's token — the subject. A long-lived app would pass
+  # D::TokenSource.authorization_code(ac_provider) instead.
+  subject: D::TokenSource.static_token(user_token),
+  actor: D::TokenSource.client_credentials(agent)
+)
+
+client = DatagroutConduit::Client.new(
+  url: "https://gateway.datagrout.ai/connect",
+  auth: { delegation: provider }
+)
+```
+
+The issued token names the user as `sub` and the agent in an `act` claim. An
+**actor token is required by default**; `impersonation: true` on the request is
+the only way to omit it, and DataGrout does not issue impersonation tokens. The
+provider caches the exchanged token, re-exchanges near expiry or after a 401,
+and consults both token sources on every exchange — so an expiring upstream
+credential is handled by the provider that owns it.
+
 ### mTLS (Mutual TLS)
 
 ```ruby

data/lib/datagrout_conduit/authcode/loopback.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+
+module DatagroutConduit
+  module AuthCode
+    # What the authorization server sent back to the redirect URI.
+    class Redirect
+      attr_reader :code, :state
+
+      def initialize(code:, state:)
+        @code = code
+        @state = state
+        freeze
+      end
+    end
+
+    # Capture the OAuth redirect on +127.0.0.1+.
+    #
+    # A native app has no web server to redirect to, so it runs one for a few
+    # seconds: bind a loopback port, send the user to the consent page, and read
+    # the +code+ off the single request the browser makes coming back.
+    #
+    # This lives in its own file rather than in {AuthCode} so a headless caller
+    # can take the flow without a listener it will never bind — the same split
+    # every conduit SDK makes, so the surface looks the same in every language.
+    # It needs nothing beyond the standard library.
+    #
+    #   listener = DatagroutConduit::AuthCode::LoopbackListener.bind
+    #   flow = DatagroutConduit::AuthCode::Flow.discover(GATEWAY)
+    #   flow.register("My App", listener.redirect_uri)
+    #
+    #   url, pending = flow.authorize_url
+    #   puts "Open: #{url}"
+    #
+    #   redirect = listener.wait(timeout: 300)
+    #   grant = flow.exchange(pending, redirect.code, redirect.state)
+    class LoopbackListener
+      # Most bytes read from a redirect request. A URL longer than this is not a
+      # redirect we can use.
+      MAX_REQUEST_BYTES = 8192
+
+      attr_reader :port
+
+      def initialize(server, port, path)
+        @server = server
+        @port = port
+        @path = path
+      end
+
+      # Bind an OS-assigned port on +127.0.0.1+.
+      #
+      # Letting the OS choose avoids fighting whatever else owns a fixed port —
+      # and because registration happens after binding, the real port is already
+      # known by the time the redirect URI is registered.
+      def self.bind
+        bind_on(0, "/callback")
+      end
+
+      # Bind a specific port and path.
+      #
+      # Use when the client was registered out of band against a fixed redirect
+      # URI and the authorization server will accept no other.
+      def self.bind_on(port, path)
+        server = begin
+          TCPServer.new("127.0.0.1", port)
+        rescue SystemCallError => e
+          raise HttpError, "cannot bind loopback port: #{e.message}"
+        end
+
+        normalized = path.to_s.start_with?("/") ? path.to_s : "/#{path}"
+        new(server, server.addr[1], normalized)
+      end
+
+      # Re-bind the exact port and path of a previously registered redirect URI.
+      #
+      # Needed whenever a saved {RegisteredClient} is reused: the authorization
+      # server matches the redirect URI exactly, so the listener has to come
+      # back on the same port it registered.
+      #
+      # Raises if that port is occupied. The right recovery is to {bind} a fresh
+      # port and register a new client — not to retry, and not to authorize
+      # against a URI the server will reject.
+      def self.bind_for(redirect_uri)
+        parsed = begin
+          URI.parse(redirect_uri.to_s)
+        rescue URI::InvalidURIError => e
+          raise HttpError, "bad redirect_uri #{redirect_uri}: #{e.message}"
+        end
+
+        raise HttpError, "bad redirect_uri #{redirect_uri}" unless parsed.scheme && parsed.host
+
+        # URI fills in the scheme's default port, so `parsed.port` cannot tell
+        # an explicit one from an absent one. The authority is what decides.
+        unless redirect_uri.to_s.include?("#{parsed.host}:#{parsed.port}")
+          raise HttpError, "redirect_uri #{redirect_uri} names no port"
+        end
+
+        bind_on(parsed.port, parsed.path.empty? ? "/" : parsed.path)
+      end
+
+      # The redirect URI to register and to send in the authorize request.
+      #
+      # Uses +127.0.0.1+ rather than +localhost+: RFC 8252 recommends the
+      # literal address, and it sidesteps hosts where +localhost+ resolves to
+      # IPv6 first while the listener is bound to IPv4.
+      def redirect_uri
+        "http://127.0.0.1:#{@port}#{@path}"
+      end
+
+      # Wait for the browser's redirect, up to +timeout+ seconds.
+      #
+      # Serves a small page either way so the user sees an outcome rather than a
+      # browser error, then stops listening. Requests to other paths are
+      # answered 404 and ignored — browsers routinely ask for +/favicon.ico+,
+      # and treating that as the redirect would abort the flow.
+      def wait(timeout: 300)
+        # A monotonic clock, because this measures an interval. Grant expiry is
+        # the opposite case and uses Unix seconds, so it survives being written
+        # down.
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if remaining <= 0 || IO.select([@server], nil, nil, remaining).nil?
+            raise HttpError,
+                  "timed out after #{timeout.round}s waiting for the authorization redirect"
+          end
+
+          outcome = handle(@server.accept)
+          next if outcome.nil?
+
+          raise outcome if outcome.is_a?(StandardError)
+
+          return outcome
+        end
+      ensure
+        close
+      end
+
+      # Stop listening. Safe to call more than once.
+      def close
+        @server.close unless @server.closed?
+      rescue IOError
+        nil
+      end
+
+      private
+
+      # Serve one request. Returns a {Redirect} on success, an exception to
+      # raise, or nil when the request was not the redirect and we should keep
+      # waiting.
+      def handle(socket)
+        target = request_target(socket.readpartial(MAX_REQUEST_BYTES))
+        return nil if target.nil?
+
+        path, _, query = target.partition("?")
+
+        unless path == @path
+          respond(socket, 404, "Not found")
+          return nil
+        end
+
+        params = parse_query(query)
+
+        if params.key?("error")
+          respond(socket, 200, "Authorization was denied. You can close this window.")
+          return DeniedError.new(error: params["error"],
+                                 description: params["error_description"])
+        end
+
+        if params.key?("code") && params.key?("state")
+          respond(socket, 200, "Signed in. You can close this window and return to the app.")
+          return Redirect.new(code: params["code"], state: params["state"])
+        end
+
+        respond(socket, 400, "Missing code or state.")
+        DiscoveryError.new("redirect carried neither an error nor a code/state pair")
+      rescue EOFError
+        nil
+      ensure
+        begin
+          socket.close
+        rescue IOError
+          nil
+        end
+      end
+
+      # The request target from a raw HTTP request line.
+      def request_target(request)
+        first = request.to_s.split(/\r?\n/, 2).first.to_s
+        parts = first.split
+        parts.length >= 2 ? parts[1] : nil
+      end
+
+      # Decode a query string.
+      #
+      # Authorization codes and state values are opaque and routinely contain
+      # characters that must survive a round trip through the query string, so
+      # +%XX+ escapes and +++ are decoded.
+      def parse_query(query)
+        query.to_s.split("&").each_with_object({}) do |pair, out|
+          key, sep, value = pair.partition("=")
+          next if sep.empty?
+
+          out[unescape(key)] = unescape(value)
+        end
+      end
+
+      def unescape(value)
+        value.tr("+", " ").gsub(/%([0-9A-Fa-f]{2})/) { Regexp.last_match(1).hex.chr }
+             .force_encoding(Encoding::UTF_8)
+      end
+
+      def respond(socket, status, message)
+        body = <<~HTML
+          <!DOCTYPE html><html><head><meta charset="utf-8"><title>DataGrout</title>
+          <style>body{font:15px/1.5 system-ui,sans-serif;margin:16vh auto;max-width:26rem;text-align:center;color-scheme:light dark}</style></head>
+          <body><p>#{message}</p></body></html>
+        HTML
+
+        socket.write(
+          "HTTP/1.1 #{status} OK\r\n" \
+          "content-type: text/html; charset=utf-8\r\n" \
+          "content-length: #{body.bytesize}\r\n" \
+          "connection: close\r\n\r\n#{body}"
+        )
+        socket.flush
+      rescue IOError, SystemCallError
+        # The browser may have closed already; the outcome is what matters.
+        nil
+      end
+    end
+  end
+end