remitmd 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b29ac02ca95fe1053bed848cca89111698f1744bbeb145681a76a3f9ed2d8e66
-  data.tar.gz: d55c4f33eaaa686fa0036e3a0566ee6382a0a544c01093a3d9887e745b2eaa01
+  metadata.gz: 8c2b03f3cb2f1a05e9a33845448154e4d34fda42f65af31823be2f30fb14b6fe
+  data.tar.gz: 3d6dc094058152593779b5430899400d7b9d6543693ee3dd35dfd08b88f4c131
 SHA512:
-  metadata.gz: 9c00d48fc571e6975d9dfd32c679d5b9cf46205742a8a725022907eb997d42de7a61ae040c22dfafb7d5a994277d25f5dafd2e589611e849f94a70c692d71102
-  data.tar.gz: dff3c27cf317ce994999efd38d57f1173f0a1136da0bf4dbcdbf1ff5879a9f737bef96875802108ca130b4e46b3b94eec1cc0f52cace3152c89357018d9f9621
+  metadata.gz: deca4edd8beb6ac2d798102a83838762d746f4508bf5e852bb1b43d74aed1fa24a7b328bc4880560fc5ab60f5bd2c937277123183c3c45cc430bf02407f5c5c8
+  data.tar.gz: c8b3bd0dc87584d00abe0b3acb37a52fa16f1f9af337780dd6aecc861f2cd542d2d684d636b28bef6b0227c13002c3c70388809d2e38a2874255bde0dd1c3932

data/README.md

@@ -24,7 +24,7 @@ gem install remitmd
 ```ruby
 require "remitmd"
 
-wallet = Remitmd::RemitWallet.new(private_key: ENV["REMITMD_PRIVATE_KEY"])
+wallet = Remitmd::RemitWallet.new(private_key: ENV["REMITMD_KEY"])
 
 # Direct payment
 tx = wallet.pay("0xRecipient0000000000000000000000000000001", 1.50)
@@ -39,12 +39,32 @@ Or from environment variables:
 
 ```ruby
 wallet = Remitmd::RemitWallet.from_env
-# Requires: REMITMD_PRIVATE_KEY
+# Requires: REMITMD_KEY (or REMIT_SIGNER_URL + REMIT_SIGNER_TOKEN)
 # Optional: REMITMD_CHAIN (default: "base"), REMITMD_API_URL
 ```
 
 Permits are auto-signed. Every payment method fetches the on-chain USDC nonce, signs an EIP-2612 permit, and includes it automatically.
 
+## Local Signer (Recommended)
+
+The local signer delegates key management to `remit signer`, a localhost HTTP server that holds your encrypted key. Your agent only needs a URL and token — no private key in the environment.
+
+```bash
+export REMIT_SIGNER_URL=http://127.0.0.1:7402
+export REMIT_SIGNER_TOKEN=rmit_sk_...
+```
+
+```ruby
+# Explicit
+signer = Remitmd::HttpSigner.new(url: "http://127.0.0.1:7402", token: "rmit_sk_...")
+wallet = Remitmd::RemitWallet.new(signer: signer)
+
+# Or auto-detect from env (recommended)
+wallet = Remitmd::RemitWallet.from_env # detects REMIT_SIGNER_URL automatically
+```
+
+`RemitWallet.from_env` detects signer credentials automatically. Priority: `REMIT_SIGNER_URL` > `REMITMD_KEY`.
+
 ## Payment Models
 
 ### Direct Payment

data/lib/remitmd/http_signer.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Remitmd
+  # Signer backed by a local HTTP signing server.
+  #
+  # Delegates digest signing to an HTTP server (typically
+  # `http://127.0.0.1:7402`). The signer server holds the encrypted key;
+  # this adapter only needs a bearer token and URL.
+  #
+  # @example
+  #   signer = Remitmd::HttpSigner.new(url: "http://127.0.0.1:7402", token: "rmit_sk_...")
+  #   wallet = Remitmd::RemitWallet.new(signer: signer, chain: "base")
+  #
+  class HttpSigner
+    include Signer
+
+    # Create an HttpSigner, fetching and caching the wallet address.
+    #
+    # @param url [String] signer server URL (e.g. "http://127.0.0.1:7402")
+    # @param token [String] bearer token for authentication
+    # @raise [RemitError] if the server is unreachable, returns an error, or returns no address
+    def initialize(url:, token:)
+      @url = url.chomp("/")
+      @token = token
+      @address = fetch_address
+    end
+
+    # Sign a 32-byte digest (raw binary bytes).
+    # Posts to /sign/digest with the hex-encoded digest.
+    # Returns a 0x-prefixed 65-byte hex signature.
+    #
+    # @param digest_bytes [String] 32-byte binary digest
+    # @return [String] 0x-prefixed 65-byte hex signature
+    # @raise [RemitError] on network, auth, policy, or server errors
+    def sign(digest_bytes)
+      hex = "0x#{digest_bytes.unpack1("H*")}"
+      uri = URI("#{@url}/sign/digest")
+      http = build_http(uri)
+
+      req = Net::HTTP::Post.new(uri.path)
+      req["Content-Type"] = "application/json"
+      req["Authorization"] = "Bearer #{@token}"
+      req.body = { digest: hex }.to_json
+
+      resp = begin
+        http.request(req)
+      rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError => e
+        raise RemitError.new(
+          RemitError::NETWORK_ERROR,
+          "HttpSigner: cannot reach signer server at #{@url}: #{e.message}"
+        )
+      end
+
+      handle_sign_response(resp)
+    end
+
+    # The cached Ethereum address (0x-prefixed).
+    # @return [String]
+    attr_reader :address
+
+    # Never expose the bearer token in inspect/to_s output.
+    def inspect
+      "#<Remitmd::HttpSigner address=#{@address}>"
+    end
+
+    alias to_s inspect
+
+    private
+
+    # Fetch the wallet address from GET /address during construction.
+    # @return [String] the 0x-prefixed Ethereum address
+    # @raise [RemitError] on any failure
+    def fetch_address
+      uri = URI("#{@url}/address")
+      http = build_http(uri)
+
+      req = Net::HTTP::Get.new(uri.path)
+      req["Authorization"] = "Bearer #{@token}"
+
+      resp = begin
+        http.request(req)
+      rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError => e
+        raise RemitError.new(
+          RemitError::NETWORK_ERROR,
+          "HttpSigner: cannot reach signer server at #{@url}: #{e.message}"
+        )
+      end
+
+      status = resp.code.to_i
+
+      if status == 401
+        raise RemitError.new(
+          RemitError::UNAUTHORIZED,
+          "HttpSigner: unauthorized -- check your REMIT_SIGNER_TOKEN"
+        )
+      end
+
+      unless (200..299).cover?(status)
+        raise RemitError.new(
+          RemitError::SERVER_ERROR,
+          "HttpSigner: GET /address failed (#{status})"
+        )
+      end
+
+      body = begin
+        JSON.parse(resp.body.to_s)
+      rescue JSON::ParserError
+        raise RemitError.new(
+          RemitError::SERVER_ERROR,
+          "HttpSigner: GET /address returned malformed JSON"
+        )
+      end
+
+      addr = body["address"]
+      if addr.nil? || addr.to_s.empty?
+        raise RemitError.new(
+          RemitError::SERVER_ERROR,
+          "HttpSigner: GET /address returned no address"
+        )
+      end
+
+      addr.to_s
+    end
+
+    # Handle the response from POST /sign/digest.
+    # @param resp [Net::HTTPResponse]
+    # @return [String] the 0x-prefixed hex signature
+    # @raise [RemitError] on any error
+    def handle_sign_response(resp)
+      status = resp.code.to_i
+
+      if status == 401
+        raise RemitError.new(
+          RemitError::UNAUTHORIZED,
+          "HttpSigner: unauthorized -- check your REMIT_SIGNER_TOKEN"
+        )
+      end
+
+      if status == 403
+        reason = begin
+          data = JSON.parse(resp.body.to_s)
+          data["reason"] || "unknown"
+        rescue JSON::ParserError
+          "unknown"
+        end
+        raise RemitError.new(
+          RemitError::UNAUTHORIZED,
+          "HttpSigner: policy denied -- #{reason}"
+        )
+      end
+
+      unless (200..299).cover?(status)
+        detail = begin
+          data = JSON.parse(resp.body.to_s)
+          data["reason"] || data["error"] || "server error"
+        rescue JSON::ParserError
+          "server error"
+        end
+        raise RemitError.new(
+          RemitError::SERVER_ERROR,
+          "HttpSigner: sign failed (#{status}): #{detail}"
+        )
+      end
+
+      body = begin
+        JSON.parse(resp.body.to_s)
+      rescue JSON::ParserError
+        raise RemitError.new(
+          RemitError::SERVER_ERROR,
+          "HttpSigner: POST /sign/digest returned malformed JSON"
+        )
+      end
+
+      sig = body["signature"]
+      if sig.nil? || sig.to_s.empty?
+        raise RemitError.new(
+          RemitError::SERVER_ERROR,
+          "HttpSigner: server returned no signature"
+        )
+      end
+
+      sig.to_s
+    end
+
+    # Build a Net::HTTP client for the given URI.
+    # @param uri [URI] the target URI
+    # @return [Net::HTTP]
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 10
+      http
+    end
+  end
+end

data/lib/remitmd/wallet.rb

@@ -67,18 +67,31 @@ module Remitmd
     end
 
     # Build a RemitWallet from environment variables.
-    # Reads: REMITMD_KEY (primary) or REMITMD_PRIVATE_KEY (deprecated fallback),
-    # REMITMD_CHAIN, REMITMD_API_URL, REMITMD_ROUTER_ADDRESS.
+    # Reads: REMIT_SIGNER_URL + REMIT_SIGNER_TOKEN (preferred, uses HttpSigner),
+    # or REMITMD_KEY (primary) / REMITMD_PRIVATE_KEY (deprecated fallback).
+    # Also reads: REMITMD_CHAIN, REMITMD_API_URL, REMITMD_ROUTER_ADDRESS.
     def self.from_env
+      chain          = ENV.fetch("REMITMD_CHAIN", "base")
+      api_url        = ENV["REMITMD_API_URL"]
+      router_address = ENV["REMITMD_ROUTER_ADDRESS"]
+
+      # Priority 1: HTTP signer server
+      signer_url = ENV["REMIT_SIGNER_URL"]
+      if signer_url
+        signer_token = ENV["REMIT_SIGNER_TOKEN"]
+        raise ArgumentError, "REMIT_SIGNER_TOKEN must be set when REMIT_SIGNER_URL is set" unless signer_token
+
+        signer = HttpSigner.new(url: signer_url, token: signer_token)
+        return new(signer: signer, chain: chain, api_url: api_url, router_address: router_address)
+      end
+
+      # Priority 2: raw private key
       key = ENV["REMITMD_KEY"] || ENV["REMITMD_PRIVATE_KEY"]
       if ENV["REMITMD_PRIVATE_KEY"] && !ENV["REMITMD_KEY"]
         warn "[remitmd] REMITMD_PRIVATE_KEY is deprecated, use REMITMD_KEY instead"
       end
-      raise ArgumentError, "REMITMD_KEY not set" unless key
+      raise ArgumentError, "REMITMD_KEY not set (or set REMIT_SIGNER_URL + REMIT_SIGNER_TOKEN)" unless key
 
-      chain          = ENV.fetch("REMITMD_CHAIN", "base")
-      api_url        = ENV["REMITMD_API_URL"]
-      router_address = ENV["REMITMD_ROUTER_ADDRESS"]
       new(private_key: key, chain: chain, api_url: api_url, router_address: router_address)
     end
 

data/lib/remitmd.rb

@@ -4,6 +4,7 @@ require_relative "remitmd/errors"
 require_relative "remitmd/models"
 require_relative "remitmd/keccak"
 require_relative "remitmd/signer"
+require_relative "remitmd/http_signer"
 require_relative "remitmd/http"
 require_relative "remitmd/wallet"
 require_relative "remitmd/mock"
@@ -25,5 +26,5 @@ require_relative "remitmd/x402_paywall"
 #   mock.was_paid?("0x0000000000000000000000000000000000000001", 1.00) # => true
 #
 module Remitmd
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: remitmd
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - remit.md
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -53,6 +53,7 @@ files:
 - lib/remitmd/a2a.rb
 - lib/remitmd/errors.rb
 - lib/remitmd/http.rb
+- lib/remitmd/http_signer.rb
 - lib/remitmd/keccak.rb
 - lib/remitmd/mock.rb
 - lib/remitmd/models.rb