datagrout-conduit 0.1.0

data/lib/datagrout_conduit/identity.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module DatagroutConduit
+  # mTLS client identity for Conduit connections.
+  #
+  # Holds the client certificate and private key presented during every TLS
+  # handshake. The server verifies the caller's identity without any
+  # application-layer token.
+  #
+  # == Auto-discovery order (try_discover)
+  #
+  # 1. +override_dir+ (if provided)
+  # 2. +CONDUIT_MTLS_CERT+ / +CONDUIT_MTLS_KEY+ env vars (PEM strings)
+  # 3. +CONDUIT_IDENTITY_DIR+ env var → directory with identity.pem + identity_key.pem
+  # 4. +~/.conduit/identity.pem+ + +identity_key.pem+
+  # 5. +.conduit/+ relative to cwd
+  class Identity
+    attr_reader :cert_pem, :key_pem, :ca_pem, :expires_at
+
+    def initialize(cert_pem:, key_pem:, ca_pem: nil, expires_at: nil)
+      validate_cert!(cert_pem)
+      validate_key!(key_pem)
+      @cert_pem = cert_pem
+      @key_pem = key_pem
+      @ca_pem = ca_pem
+      @expires_at = expires_at
+    end
+
+    # Build from PEM strings already in memory.
+    def self.from_pem(cert_pem, key_pem, ca_pem: nil)
+      new(cert_pem: cert_pem, key_pem: key_pem, ca_pem: ca_pem)
+    end
+
+    # Build by reading PEM files from disk.
+    def self.from_paths(cert_path, key_path, ca_path: nil)
+      cert_pem = File.read(cert_path)
+      key_pem = File.read(key_path)
+      ca_pem = ca_path ? File.read(ca_path) : nil
+      new(cert_pem: cert_pem, key_pem: key_pem, ca_pem: ca_pem)
+    rescue Errno::ENOENT => e
+      raise ConfigError, "Cannot read identity file: #{e.message}"
+    end
+
+    # Build from environment variables.
+    #
+    # Variables:
+    # - CONDUIT_MTLS_CERT — PEM string for the client certificate
+    # - CONDUIT_MTLS_KEY  — PEM string for the private key
+    # - CONDUIT_MTLS_CA   — PEM string for the CA (optional)
+    #
+    # Returns nil if CONDUIT_MTLS_CERT is not set.
+    def self.from_env
+      cert = ENV["CONDUIT_MTLS_CERT"]
+      return nil if cert.nil? || cert.empty?
+
+      key = ENV["CONDUIT_MTLS_KEY"]
+      raise ConfigError, "CONDUIT_MTLS_CERT is set but CONDUIT_MTLS_KEY is missing" if key.nil? || key.empty?
+
+      ca = ENV["CONDUIT_MTLS_CA"]
+      ca = nil if ca && ca.empty?
+
+      new(cert_pem: cert, key_pem: key, ca_pem: ca)
+    end
+
+    # Walk the auto-discovery chain and return the first identity found,
+    # or nil if nothing is available.
+    def self.try_discover(override_dir: nil)
+      # 1. Override directory
+      if override_dir
+        id = try_load_from_dir(override_dir)
+        return id if id
+      end
+
+      # 2. Environment variables (individual cert/key PEMs)
+      id = from_env
+      return id if id
+
+      # 3. CONDUIT_IDENTITY_DIR env var
+      identity_dir = ENV["CONDUIT_IDENTITY_DIR"]
+      if identity_dir && !identity_dir.empty?
+        id = try_load_from_dir(identity_dir)
+        return id if id
+      end
+
+      # 4. ~/.conduit/
+      home = ENV["HOME"] || ENV["USERPROFILE"]
+      if home
+        id = try_load_from_dir(File.join(home, ".conduit"))
+        return id if id
+      end
+
+      # 5. .conduit/ relative to cwd
+      id = try_load_from_dir(File.join(Dir.pwd, ".conduit"))
+      return id if id
+
+      nil
+    rescue ConfigError
+      nil
+    end
+
+    def with_expiry(expires_at)
+      dup.tap { |i| i.instance_variable_set(:@expires_at, expires_at) }
+    end
+
+    # Returns true if the certificate expires within +threshold_days+.
+    # Returns false when no expiry is known.
+    def needs_rotation?(threshold_days: 30)
+      return false if @expires_at.nil?
+
+      deadline = Time.now + (threshold_days * 86_400)
+      deadline > @expires_at
+    end
+
+    # Return an OpenSSL::X509::Certificate for use with Faraday SSL config.
+    def openssl_cert
+      OpenSSL::X509::Certificate.new(@cert_pem)
+    end
+
+    # Return an OpenSSL::PKey for use with Faraday SSL config.
+    def openssl_key
+      OpenSSL::PKey.read(@key_pem)
+    end
+
+    # Return an OpenSSL::X509::Certificate for the CA, if present.
+    def openssl_ca
+      @ca_pem ? OpenSSL::X509::Certificate.new(@ca_pem) : nil
+    end
+
+    # Configure Faraday SSL options with this identity's mTLS credentials.
+    def configure_ssl(ssl)
+      ssl.client_cert = openssl_cert
+      ssl.client_key = openssl_key
+      if @ca_pem
+        store = OpenSSL::X509::Store.new
+        store.add_cert(openssl_ca)
+        ssl.cert_store = store
+      end
+    end
+
+    class << self
+      private
+
+      def try_load_from_dir(dir)
+        cert_path = File.join(dir, "identity.pem")
+        key_path = File.join(dir, "identity_key.pem")
+        return nil unless File.exist?(cert_path) && File.exist?(key_path)
+
+        ca_path = File.join(dir, "ca.pem")
+        ca = File.exist?(ca_path) ? ca_path : nil
+
+        from_paths(cert_path, key_path, ca_path: ca)
+      rescue ConfigError
+        nil
+      end
+    end
+
+    private
+
+    def validate_cert!(pem)
+      unless pem.include?("-----BEGIN CERTIFICATE-----")
+        raise ConfigError, "cert_pem does not appear to contain a PEM certificate"
+      end
+    end
+
+    def validate_key!(pem)
+      valid = pem.include?("-----BEGIN PRIVATE KEY-----") ||
+              pem.include?("-----BEGIN RSA PRIVATE KEY-----") ||
+              pem.include?("-----BEGIN EC PRIVATE KEY-----") ||
+              pem.include?("-----BEGIN ENCRYPTED PRIVATE KEY-----")
+      raise ConfigError, "key_pem does not appear to contain a PEM private key" unless valid
+    end
+  end
+end

data/lib/datagrout_conduit/oauth.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+module DatagroutConduit
+  module OAuth
+    # Lazily fetches and caches OAuth 2.1 client_credentials tokens.
+    # Thread-safe via Mutex.
+    class TokenProvider
+      REFRESH_BUFFER_SECONDS = 60
+
+      attr_reader :client_id, :token_endpoint
+
+      def initialize(client_id:, client_secret:, token_endpoint:, scope: nil)
+        @client_id = client_id
+        @client_secret = client_secret
+        @token_endpoint = token_endpoint
+        @scope = scope
+        @mutex = Mutex.new
+        @cached_token = nil
+        @expires_at = nil
+      end
+
+      # Derive the token endpoint from an MCP URL.
+      #
+      #   "https://app.datagrout.ai/servers/abc/mcp"
+      #   => "https://app.datagrout.ai/servers/abc/oauth/token"
+      def self.derive_token_endpoint(mcp_url)
+        idx = mcp_url.index("/mcp")
+        base = idx ? mcp_url[0...idx] : mcp_url.chomp("/")
+        "#{base}/oauth/token"
+      end
+
+      # Return a valid bearer token, fetching or refreshing as needed.
+      def get_token
+        @mutex.synchronize do
+          return @cached_token if token_valid?
+
+          fetch_token!
+          @cached_token
+        end
+      end
+
+      # Force-invalidate the cached token (e.g. on receipt of a 401).
+      def invalidate!
+        @mutex.synchronize do
+          @cached_token = nil
+          @expires_at = nil
+        end
+      end
+
+      private
+
+      def token_valid?
+        @cached_token && @expires_at && (Time.now < @expires_at - REFRESH_BUFFER_SECONDS)
+      end
+
+      def fetch_token!
+        conn = Faraday.new(url: @token_endpoint) do |f|
+          f.request :url_encoded
+          f.adapter Faraday.default_adapter
+        end
+
+        params = {
+          "grant_type" => "client_credentials",
+          "client_id" => @client_id,
+          "client_secret" => @client_secret
+        }
+        params["scope"] = @scope if @scope
+
+        response = conn.post { |req| req.body = params }
+
+        unless response.success?
+          raise AuthError, "OAuth token endpoint returned #{response.status}: #{response.body}"
+        end
+
+        data = JSON.parse(response.body)
+        @cached_token = data["access_token"]
+        expires_in = (data["expires_in"] || 3600).to_i
+        @expires_at = Time.now + expires_in
+      end
+    end
+  end
+end

data/lib/datagrout_conduit/registration.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "fileutils"
+require "faraday"
+require "json"
+
+module DatagroutConduit
+  # Substrate identity registration with the DataGrout CA.
+  #
+  # Handles the issuance flow — turning a freshly-generated keypair into a
+  # DG-CA-signed Identity that DataGrout will accept for mTLS.
+  #
+  # == Flow
+  #
+  # 1. Generate an ECDSA P-256 keypair with {.generate_keypair}.
+  #    The private key never leaves the client.
+  # 2. Send the *public key* to the DataGrout CA via {.register_identity}
+  #    (authenticated with a bearer token — user access token or API key).
+  # 3. Persist the returned identity to +~/.conduit/+ via {.save_identity}
+  #    for auto-discovery by future sessions.
+  # 4. On renewal (cert near expiry), call {.rotate_identity} which presents
+  #    the *existing* client certificate over mTLS — no API key needed.
+  class Registration
+    DG_CA_URL = "https://ca.datagrout.ai/ca.pem"
+    DG_SUBSTRATE_ENDPOINT = "https://app.datagrout.ai/api/v1/substrate/identity"
+
+    # Generate an ECDSA P-256 keypair.
+    #
+    # @return [Array(String, String)] +[private_key_pem, public_key_pem]+
+    def self.generate_keypair
+      key = OpenSSL::PKey::EC.generate("prime256v1")
+      private_pem = key.to_pem
+
+      public_pem = if key.respond_to?(:public_to_pem)
+                     key.public_to_pem
+                   else
+                     pub = OpenSSL::PKey::EC.new(key.group)
+                     pub.public_key = key.public_key
+                     pub.to_pem
+                   end
+
+      [private_pem, public_pem]
+    end
+
+    # Register identity with the DataGrout CA.
+    #
+    # Sends only the public key. The private key never leaves the client.
+    # Authenticated with a bearer token (user access token or API key).
+    #
+    # @param public_key_pem [String] PEM-encoded public key
+    # @param auth_token [String] bearer token for authentication
+    # @param name [String] human-readable label for the substrate instance
+    # @param substrate_endpoint [String] registration endpoint URL
+    # @return [RegistrationResponse]
+    def self.register_identity(public_key_pem, auth_token:, name: "conduit-client",
+                               substrate_endpoint: DG_SUBSTRATE_ENDPOINT)
+      conn = Faraday.new(url: substrate_endpoint) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+      end
+
+      response = conn.post do |req|
+        req.url "register"
+        req.headers["Authorization"] = "Bearer #{auth_token}"
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(
+          name: name,
+          public_key_pem: public_key_pem
+        )
+      end
+
+      unless response.success?
+        raise AuthError, "Registration failed (HTTP #{response.status}): #{response.body}"
+      end
+
+      body = response.body
+      body = JSON.parse(body) if body.is_a?(String)
+
+      RegistrationResponse.new(
+        id: body["id"],
+        cert_pem: body["cert_pem"],
+        ca_cert_pem: body["ca_cert_pem"],
+        fingerprint: body["fingerprint"],
+        name: body["name"],
+        registered_at: body["registered_at"],
+        valid_until: body["valid_until"]
+      )
+    end
+
+    # Rotate identity using existing mTLS cert.
+    #
+    # Generates a new public key, sends it to the +/rotate+ endpoint
+    # authenticated by the *current* cert over mTLS (no API key needed),
+    # and returns a fresh DG-CA-signed certificate.
+    #
+    # @param identity [Identity] current mTLS identity for authentication
+    # @param new_public_key_pem [String] PEM-encoded new public key
+    # @param name [String] human-readable label
+    # @param substrate_endpoint [String] registration endpoint URL
+    # @return [RegistrationResponse]
+    def self.rotate_identity(identity, new_public_key_pem, name: "conduit-client",
+                             substrate_endpoint: DG_SUBSTRATE_ENDPOINT)
+      conn = Faraday.new(url: substrate_endpoint) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+        identity.configure_ssl(f.ssl)
+      end
+
+      response = conn.post do |req|
+        req.url "rotate"
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(
+          name: name,
+          public_key_pem: new_public_key_pem
+        )
+      end
+
+      unless response.success?
+        raise ConnectionError, "Rotation failed (HTTP #{response.status}): #{response.body}"
+      end
+
+      body = response.body
+      body = JSON.parse(body) if body.is_a?(String)
+
+      RegistrationResponse.new(
+        id: body["id"],
+        cert_pem: body["cert_pem"],
+        ca_cert_pem: body["ca_cert_pem"],
+        fingerprint: body["fingerprint"],
+        name: body["name"],
+        registered_at: body["registered_at"],
+        valid_until: body["valid_until"]
+      )
+    end
+
+    # Save identity files to a directory with secure permissions (0600).
+    #
+    # @param cert_pem [String] DG-signed certificate PEM
+    # @param key_pem [String] private key PEM
+    # @param dir [String] directory path
+    # @param ca_pem [String, nil] CA certificate PEM
+    # @return [Hash] paths to written files (+:cert+, +:key+, +:ca+)
+    def self.save_identity(cert_pem, key_pem, dir, ca_pem: nil)
+      FileUtils.mkdir_p(dir)
+
+      cert_path = File.join(dir, "identity.pem")
+      key_path = File.join(dir, "identity_key.pem")
+
+      File.write(cert_path, cert_pem)
+      File.write(key_path, key_pem)
+      File.chmod(0o600, cert_path)
+      File.chmod(0o600, key_path)
+
+      paths = { cert: cert_path, key: key_path }
+
+      if ca_pem
+        ca_path = File.join(dir, "ca.pem")
+        File.write(ca_path, ca_pem)
+        File.chmod(0o600, ca_path)
+        paths[:ca] = ca_path
+      end
+
+      paths
+    end
+
+    # Fetch the DataGrout CA certificate from +ca.datagrout.ai+.
+    #
+    # Uses the system trust store for TLS (not the DG CA itself), so there
+    # is no circularity.
+    #
+    # @param ca_url [String] URL to fetch the CA cert from
+    # @return [String] PEM-encoded CA certificate
+    def self.fetch_ca_cert(ca_url: DG_CA_URL)
+      response = Faraday.get(ca_url)
+
+      unless response.success?
+        raise ConnectionError, "Failed to fetch CA cert (HTTP #{response.status})"
+      end
+
+      pem = response.body
+      unless pem.include?("-----BEGIN CERTIFICATE-----")
+        raise ConnectionError, "Response from #{ca_url} does not look like a PEM certificate"
+      end
+
+      pem
+    end
+
+    # Refresh CA cert in the given directory.
+    #
+    # @param dir [String] directory to write +ca.pem+ into
+    # @param ca_url [String] URL to fetch the CA cert from
+    # @return [String] path to the written +ca.pem+ file
+    def self.refresh_ca_cert(dir, ca_url: DG_CA_URL)
+      ca_pem = fetch_ca_cert(ca_url: ca_url)
+      FileUtils.mkdir_p(dir)
+      ca_path = File.join(dir, "ca.pem")
+      File.write(ca_path, ca_pem)
+      File.chmod(0o600, ca_path)
+      ca_path
+    end
+
+    # Returns +~/.conduit/+ as the canonical identity directory.
+    #
+    # @return [String, nil]
+    def self.default_identity_dir
+      home = ENV["HOME"] || ENV["USERPROFILE"]
+      home ? File.join(home, ".conduit") : nil
+    end
+  end
+
+  RegistrationResponse = Struct.new(
+    :id, :cert_pem, :ca_cert_pem, :fingerprint,
+    :name, :registered_at, :valid_until,
+    keyword_init: true
+  )
+end

data/lib/datagrout_conduit/transport/base.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "base64"
+require "securerandom"
+
+module DatagroutConduit
+  module Transport
+    # Base transport shared by MCP and JSONRPC transports.
+    # Manages a Faraday connection with optional mTLS and auth headers.
+    class Base
+      attr_reader :url
+
+      def initialize(url:, auth: {}, identity: nil)
+        @url = url
+        @auth = normalize_auth(auth)
+        @identity = identity
+        @connected = false
+        @connection = build_connection
+      end
+
+      def connect
+        URI.parse(@url) # validate URL
+        @connected = true
+      end
+
+      def disconnect
+        @connected = false
+      end
+
+      def connected?
+        @connected
+      end
+
+      # Subclasses must implement this.
+      def send_request(_method, _params = nil, id: nil)
+        raise NotImplementedError, "#{self.class}#send_request must be implemented"
+      end
+
+      private
+
+      def ensure_connected!
+        raise NotInitializedError unless @connected
+      end
+
+      def next_id
+        SecureRandom.uuid
+      end
+
+      def build_connection
+        Faraday.new(url: @url) do |f|
+          f.request :json
+          f.response :json, content_type: /\bjson$/
+          f.adapter Faraday.default_adapter
+
+          configure_ssl(f) if @identity
+        end
+      end
+
+      def configure_ssl(faraday)
+        faraday.ssl.client_cert = @identity.openssl_cert
+        faraday.ssl.client_key = @identity.openssl_key
+        if @identity.ca_pem
+          store = OpenSSL::X509::Store.new
+          store.add_cert(@identity.openssl_ca)
+          faraday.ssl.cert_store = store
+        end
+      end
+
+      def build_headers
+        headers = { "Content-Type" => "application/json" }
+
+        case @auth[:type]
+        when :bearer
+          headers["Authorization"] = "Bearer #{@auth[:token]}"
+        when :api_key
+          headers["X-API-Key"] = @auth[:key]
+        when :basic
+          encoded = Base64.strict_encode64("#{@auth[:username]}:#{@auth[:password]}")
+          headers["Authorization"] = "Basic #{encoded}"
+        when :oauth
+          token = @auth[:provider].get_token
+          headers["Authorization"] = "Bearer #{token}"
+        end
+
+        headers
+      end
+
+      def build_jsonrpc_body(method, params, id)
+        body = {
+          "jsonrpc" => "2.0",
+          "id" => id || next_id,
+          "method" => method
+        }
+        body["params"] = params if params
+        body
+      end
+
+      def handle_response(response)
+        check_rate_limit!(response)
+
+        if response.status == 401 && @auth[:type] == :oauth
+          @auth[:provider].invalidate!
+          return :retry_oauth
+        end
+
+        return { "accepted" => true } if response.status == 202
+
+        unless response.success?
+          raise ConnectionError, "HTTP #{response.status} error"
+        end
+
+        body = response.body
+        body = JSON.parse(body) if body.is_a?(String)
+
+        if body.is_a?(Hash) && body["error"]
+          err = body["error"]
+          raise McpError.new(
+            code: err["code"] || -1,
+            message: err["message"] || "Unknown error",
+            data: err["data"]
+          )
+        end
+
+        body
+      end
+
+      def check_rate_limit!(response)
+        return unless response.status == 429
+
+        used = response.headers["X-RateLimit-Used"]&.to_i || 0
+        limit_str = response.headers["X-RateLimit-Limit"] || "50"
+        limit = limit_str.casecmp("unlimited").zero? ? "unlimited" : limit_str.to_i
+
+        raise RateLimitedError.new(used: used, limit: limit)
+      end
+
+      def normalize_auth(auth)
+        return { type: :none } if auth.nil? || auth.empty?
+
+        auth = auth.transform_keys(&:to_sym) if auth.is_a?(Hash)
+
+        if auth[:bearer]
+          { type: :bearer, token: auth[:bearer] }
+        elsif auth[:api_key]
+          { type: :api_key, key: auth[:api_key] }
+        elsif auth[:basic]
+          { type: :basic, username: auth[:basic][:username], password: auth[:basic][:password] }
+        elsif auth[:oauth] || auth[:provider]
+          { type: :oauth, provider: auth[:oauth] || auth[:provider] }
+        else
+          { type: :none }
+        end
+      end
+    end
+  end
+end

data/lib/datagrout_conduit/transport/jsonrpc.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module DatagroutConduit
+  module Transport
+    # JSON-RPC over HTTP POST transport.
+    # Sends standard JSON-RPC 2.0 requests via HTTP POST.
+    class JsonRpc < Base
+      def send_request(method, params = nil, id: nil)
+        ensure_connected!
+
+        request_id = id || next_id
+        body = build_jsonrpc_body(method, params, request_id)
+        headers = build_headers
+
+        response = @connection.post do |req|
+          req.headers = headers
+          req.body = JSON.generate(body)
+        end
+
+        result = handle_response(response)
+
+        if result == :retry_oauth
+          headers = build_headers
+          response = @connection.post do |req|
+            req.headers = headers
+            req.body = JSON.generate(body)
+          end
+          result = handle_response(response)
+          raise AuthError, "OAuth token rejected after refresh" if result == :retry_oauth
+        end
+
+        result
+      end
+    end
+  end
+end