openhub-bo-core 0.1.0

data/ext/openhub_bo_core/vendor/openhub-bo-core/src/webhook.rs

@@ -0,0 +1,132 @@
+//! Webhook pieces shared by every product family. ATC does not sign payloads:
+//! it echoes the static header configured in [`WebhookTarget`]. Payload
+//! parsing is family-specific and lives with each family.
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+use subtle::ConstantTimeEq;
+
+use crate::error::{Error, Result};
+use crate::validate::require_text;
+
+/// Where ATC must POST notifications, and the static header it will send so
+/// the integrator can authenticate the call.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct WebhookTarget {
+    pub url: String,
+    /// Header name, e.g. `x-api-key`.
+    pub key: String,
+    /// Header value; treat it as a secret.
+    pub value: String,
+}
+
+impl WebhookTarget {
+    pub fn validate(&self) -> Result<()> {
+        let url = self.url.trim();
+        if !(url.starts_with("https://") || url.starts_with("http://")) {
+            return Err(Error::validation("webhook.url", "must be an http(s) URL"));
+        }
+        require_text("webhook.key", &self.key)?;
+        if !self
+            .key
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
+        {
+            return Err(Error::validation(
+                "webhook.key",
+                "must be a valid HTTP header name",
+            ));
+        }
+        require_text("webhook.value", &self.value)
+    }
+}
+
+/// An incoming webhook call as received by the integrator, plus the header
+/// name/value configured when the payment was created. Input of every
+/// family's webhook handler.
+#[derive(Debug, Clone, Deserialize)]
+pub struct WebhookCall {
+    pub headers: BTreeMap<String, String>,
+    pub body: String,
+    /// Header name and value sent as `webhook.key` / `webhook.value`.
+    pub key: String,
+    pub value: String,
+}
+
+impl WebhookCall {
+    pub fn authenticate(&self) -> Result<()> {
+        authenticate(&self.headers, &self.key, &self.value)
+    }
+}
+
+/// Checks the auth header of an incoming webhook: name case-insensitive,
+/// value in constant time.
+pub fn authenticate(headers: &BTreeMap<String, String>, key: &str, value: &str) -> Result<()> {
+    if value.is_empty() {
+        return Err(Error::validation(
+            "value",
+            "expected webhook header value must not be empty",
+        ));
+    }
+    let received = headers
+        .iter()
+        .find(|(name, _)| name.eq_ignore_ascii_case(key))
+        .map(|(_, v)| v.as_str())
+        .ok_or_else(|| Error::WebhookAuth {
+            message: format!("missing `{key}` header"),
+        })?;
+    verify_secret(&format!("`{key}` header"), received, value)
+}
+
+/// Constant-time comparison of a received secret (header, query token...).
+pub fn verify_secret(what: &str, received: &str, expected: &str) -> Result<()> {
+    if expected.is_empty() {
+        return Err(Error::validation(
+            "value",
+            "expected secret must not be empty",
+        ));
+    }
+    if !bool::from(received.as_bytes().ct_eq(expected.as_bytes())) {
+        return Err(Error::WebhookAuth {
+            message: format!("{what} does not match"),
+        });
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn headers(name: &str, value: &str) -> BTreeMap<String, String> {
+        BTreeMap::from([(name.to_owned(), value.to_owned())])
+    }
+
+    #[test]
+    fn authenticates_case_insensitively() {
+        assert!(authenticate(&headers("X-API-KEY", "s3cret"), "x-api-key", "s3cret").is_ok());
+    }
+
+    #[test]
+    fn rejects_wrong_or_missing_header() {
+        for h in [headers("x-api-key", "nope"), headers("other", "s3cret")] {
+            assert!(matches!(
+                authenticate(&h, "x-api-key", "s3cret"),
+                Err(Error::WebhookAuth { .. })
+            ));
+        }
+    }
+
+    #[test]
+    fn validates_target() {
+        let target = |url: &str, key: &str| WebhookTarget {
+            url: url.into(),
+            key: key.into(),
+            value: "v".into(),
+        };
+        assert!(target("https://a.bo/h", "x-api-key").validate().is_ok());
+        assert!(target("ftp://a.bo", "x-api-key").validate().is_err());
+        assert!(target("https://a.bo", "bad key").validate().is_err());
+    }
+}

data/lib/openhub_bo/core/errors.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    ApiFieldError = Data.define(:message, :field, :code)
+
+    # Base class for every error raised by openhub-bo.
+    class Error < StandardError
+      # Whether repeating the same call later may succeed.
+      def retryable? = false
+    end
+
+    # Input rejected locally, before calling OpenHub.
+    class ValidationError < Error
+      attr_reader :field
+
+      def initialize(message, field:)
+        super("invalid `#{field}`: #{message}")
+        @field = field
+      end
+    end
+
+    # Credentials or access token rejected by OpenHub.
+    class AuthenticationError < Error
+      attr_reader :status
+
+      def initialize(message, status:)
+        super("authentication failed (HTTP #{status}): #{message}")
+        @status = status
+      end
+    end
+
+    # OpenHub answered with an error.
+    class ApiError < Error
+      attr_reader :status, :errors
+
+      def initialize(message, status:, errors: [], retryable: false)
+        super("OpenHub error (HTTP #{status}): #{message}")
+        @status = status
+        @errors = errors
+        @retryable = retryable
+      end
+
+      def retryable? = @retryable
+
+      # Code of the first field error, e.g. "TRANSACCION_NO_ENCONTRADA".
+      def code = errors.map(&:code).compact.first
+    end
+
+    # The response could not be understood.
+    class DecodeError < Error; end
+
+    # Incoming webhook did not carry the expected secret.
+    class WebhookAuthError < Error; end
+
+    # Network failure. `maybe_sent` is false when the request never left
+    # (connection refused, connect timeout): retrying is then always safe.
+    class TransportError < Error
+      attr_reader :maybe_sent
+
+      def initialize(message, maybe_sent:)
+        super(message)
+        @maybe_sent = maybe_sent
+      end
+
+      def retryable? = true
+    end
+
+    # A non-idempotent call (generating a QR, paying a payout...) may or may not
+    # have been applied: the response was lost, or OpenHub reported the result as
+    # unconfirmed (payout codes 94/96). Deliberately not a TransportError so
+    # generic retry loops do not repeat it. Query the status before retrying.
+    class AmbiguousOutcomeError < Error
+      attr_reader :operation, :errors
+
+      def initialize(operation, cause, errors: [])
+        super("outcome of `#{operation}` is unknown: #{cause}")
+        @operation = operation
+        @errors = errors
+      end
+
+      def code = errors.map(&:code).compact.first
+    end
+
+    # Contract violation between a gem and its native extension (a bug).
+    class CoreError < Error; end
+
+    module_function
+
+    # Maps an error from the native core; `op` is the native op name
+    # (e.g. "payouts.pay.parse").
+    def error_from_core(data, op = "")
+      kind = data["kind"]
+      message = data.fetch("message", "unknown error")
+      errors = Array(data["errors"]).map do |e|
+        ApiFieldError.new(message: e["message"], field: e["field"], code: e["code"])
+      end
+      case kind
+      when "validation" then ValidationError.new(message, field: data["field"])
+      when "authentication" then AuthenticationError.new(message, status: data["status"])
+      when "api"
+        ApiError.new(message, status: data["status"], errors: errors, retryable: data["retryable"] == true)
+      when "ambiguous"
+        AmbiguousOutcomeError.new(op.sub(/\.(build|parse)\z/, ""), message, errors: errors)
+      when "decode" then DecodeError.new(message)
+      when "webhook_auth" then WebhookAuthError.new(message)
+      else CoreError.new(message)
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/models.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module OpenhubBo
+  module Core
+    module Environment
+      DEVELOPMENT = :development
+      SANDBOX = :sandbox
+      PRODUCTION = :production
+      ALL = [DEVELOPMENT, SANDBOX, PRODUCTION].freeze
+    end
+
+    # Status shared by every product family (symbols); `raw_status` keeps the original.
+    module PaymentStatus
+      ALL = %i[pending processing paid cancelled expired rejected reversed error unknown].freeze
+      NOT_FINAL = %i[pending processing unknown].freeze
+
+      def self.final?(status) = !NOT_FINAL.include?(status)
+    end
+
+    # OpenHub timestamps carry no offset: they are Bolivia time.
+    BOLIVIA_OFFSET = "-04:00"
+
+    # Where ATC must POST notifications. ATC sends `key: value` as a header; it is
+    # the only authentication, so use a long random value.
+    Webhook = Data.define(:url, :value, :key) do
+      def initialize(url:, value:, key: "x-api-key") = super
+
+      def to_wire = { "url" => url, "key" => key, "value" => value }
+
+      def inspect = "#<#{self.class.name} url=#{url.inspect} key=#{key.inspect} value=[FILTERED]>"
+      alias_method :to_s, :inspect
+    end
+
+    module_function
+
+    # Amounts cross the native boundary as exact decimal strings.
+    def amount(value)
+      case value
+      when BigDecimal then value.to_s("F")
+      when Integer then value.to_s
+      when String then value
+      else
+        raise TypeError,
+              "amount must be BigDecimal, Integer or String, not #{value.class} " \
+              "(floats are rejected to avoid rounding errors)"
+      end
+    end
+
+    def seconds(value)
+      raise TypeError, "expected Integer seconds, not #{value.class}" unless value.is_a?(Integer)
+
+      value
+    end
+
+    def iso_date(value) = value.is_a?(Date) ? value.iso8601 : value
+
+    def decimal(value) = value.nil? ? nil : BigDecimal(value)
+
+    # Parses an OpenHub timestamp, assuming Bolivia time when it has no offset.
+    def local_time(value)
+      return nil if value.nil? || value.empty?
+
+      has_offset = value.match?(/(Z|[+-]\d{2}:?\d{2})\z/)
+      Time.iso8601(has_offset ? value : value.tr(" ", "T") + BOLIVIA_OFFSET)
+    rescue ArgumentError
+      nil
+    end
+
+    # Defines an immutable value class from the core's snake_case JSON.
+    #
+    #   Payer = Core.model(:name, :document_id)
+    #   Qr = Core.model(:reference, :amount, :payer, casts: { amount: :decimal, payer: Payer })
+    #
+    # Casts: :decimal (BigDecimal), :symbol, :time (Bolivia time), a model class,
+    # or [ModelClass] for lists.
+    def model(*fields, casts: {}, &block)
+      klass = Data.define(*fields, &block)
+      klass.define_singleton_method(:from_h) do |hash|
+        return nil if hash.nil?
+
+        attrs = fields.to_h { |field| [field, Core.cast(hash[field.to_s], casts[field])] }
+        new(**attrs)
+      end
+      klass
+    end
+
+    def cast(value, how)
+      return value if how.nil? || value.nil?
+
+      case how
+      when :decimal then BigDecimal(value.to_s)
+      when :symbol then value.to_sym
+      when :time then local_time(value)
+      when Array then value.map { |item| how.first.from_h(item) }
+      else how.from_h(value)
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/native_bridge.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    # A native extension exposing `call(op, payload) -> String`. Checks the
+    # protocol on load and caches the operation catalog from `describe`, so
+    # declared operations are validated when the gem is required.
+    class NativeBridge
+      attr_reader :operations, :version
+
+      def initialize(mod)
+        protocol = mod.protocol_version
+        unless protocol == SUPPORTED_PROTOCOL
+          raise LoadError,
+                "#{mod} speaks core protocol #{protocol}, this gem expects #{SUPPORTED_PROTOCOL}; " \
+                "install matching openhub-bo versions"
+        end
+        @mod = mod
+        @version = mod.version
+        @operations = invoke("describe", {}).to_h { |entry| [entry["name"], entry] }.freeze
+      end
+
+      def invoke(op, payload)
+        result = JSON.parse(@mod.call(op, JSON.generate(payload)))
+        return result["value"] if result["ok"]
+
+        raise Core.error_from_core(result["error"], op)
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/op.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    # An HTTP endpoint implemented by a native extension. Declaring one with a
+    # name the extension does not know raises LoadError at require time.
+    class Op
+      attr_reader :native, :name
+
+      def initialize(native, name, &decode)
+        info = native.operations[name]
+        raise LoadError, "native extension has no operation `#{name}`" unless info && info["kind"] == "operation"
+
+        @native = native
+        @name = name
+        @decode = decode || ->(value) { value }
+        @info = info
+      end
+
+      def idempotent? = @info["idempotent"] == true
+
+      # Client timeout (seconds) recommended by ATC for this endpoint, if any.
+      def timeout = @info["timeout_secs"]
+
+      def build(config, token, input)
+        request = native.invoke("#{name}.build", { "config" => config, "token" => token, "input" => input })
+        request["timeout"] = timeout if timeout
+        request
+      end
+
+      def parse(input, response)
+        @decode.call(native.invoke("#{name}.parse", { "input" => input, "response" => response.to_wire }))
+      end
+    end
+
+    # A pure native function (no HTTP), e.g. webhook parsing.
+    class Handler
+      def initialize(native, name, &decode)
+        info = native.operations[name]
+        raise LoadError, "native extension has no handler `#{name}`" unless info && info["kind"] == "handler"
+
+        @native = native
+        @name = name
+        @decode = decode || ->(value) { value }
+      end
+
+      def call(input) = @decode.call(@native.invoke(@name, input))
+    end
+  end
+end

data/lib/openhub_bo/core/session.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    NATIVE = NativeBridge.new(Native)
+    TOKEN = Op.new(NATIVE, "token")
+
+    # Credentials, token cache and execution of operations. Share one session
+    # between product clients (QrClient.new(session), PixClient.new(session)...)
+    # so they reuse the OAuth token. Thread-safe.
+    class Session
+      attr_reader :environment
+
+      def initialize(client_id, client_secret = nil, basic_token: nil, environment: Environment::SANDBOX,
+                     base_url: nil, timeout: 30, transport: nil)
+        @environment = environment.to_sym
+        unless Environment::ALL.include?(@environment)
+          raise ValidationError.new("must be one of #{Environment::ALL.join(', ')}", field: "environment")
+        end
+
+        @config = {
+          "client_id" => client_id,
+          "client_secret" => client_secret,
+          "basic_token" => basic_token,
+          "environment" => @environment.to_s,
+          "base_url" => base_url
+        }
+        @transport = transport || NetHttpTransport.new(timeout: timeout)
+        @token = nil
+        @lock = Mutex.new
+        # Fail fast on missing credentials instead of at the first request.
+        TOKEN.build(@config, nil, token_input)
+      end
+
+      # Runs `op`: token, build, send, parse; refreshes a rejected token once.
+      def execute(op, input)
+        2.times do |attempt|
+          token = ensure_token
+          response = deliver(op, op.build(@config, token, input))
+          begin
+            return op.parse(input, response)
+          rescue AuthenticationError
+            raise if attempt == 1
+
+            invalidate(token)
+          end
+        end
+      end
+
+      def close = @transport.close
+
+      def inspect = "#<#{self.class.name} client_id=#{@config['client_id'].inspect} environment=#{@environment}>"
+      alias_method :to_s, :inspect
+
+      private
+
+      def ensure_token
+        @lock.synchronize do
+          token = @token
+          return token if token && Time.now.to_i < token["expires_at"]
+
+          @token = TOKEN.parse(token_input, deliver(TOKEN, TOKEN.build(@config, nil, token_input)))
+        end
+      end
+
+      def invalidate(token)
+        @lock.synchronize { @token = nil if @token && @token["access_token"] == token["access_token"] }
+      end
+
+      def deliver(op, request)
+        @transport.perform(request)
+      rescue TransportError => e
+        raise AmbiguousOutcomeError.new(op.name, e) if e.maybe_sent && !op.idempotent?
+
+        raise
+      end
+
+      def token_input = { "now" => Time.now.to_i }
+    end
+  end
+end

data/lib/openhub_bo/core/testing.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "openhub_bo/core"
+
+module OpenhubBo
+  module Core
+    module Testing
+      # In-memory fake of the OpenHub gateway (Sensedia): handles the OAuth token
+      # and the access_token/client_id check like the real gateway; tests or
+      # product gems register routes on top. Use it as a Session transport:
+      #
+      #   gateway = MockGateway.new
+      #   gateway.route("GET", %r{/qr/simple/v2/verify/(\d+)\z}) { |req, m| Response.new(status: 200, body: "...") }
+      #   session = gateway.session
+      class MockGateway
+        BASE_URL = "https://openhub.mock"
+        TOKEN_PATH = "/oauth-client-credentials/access-token"
+
+        attr_reader :client_id, :client_secret, :requests, :token_requests
+
+        def initialize(client_id: "test-client", client_secret: "test-secret", token_ttl: 3600)
+          @client_id = client_id
+          @client_secret = client_secret
+          @token_ttl = token_ttl
+          @requests = []
+          @token_requests = 0
+          @tokens = []
+          @routes = []
+        end
+
+        def route(method, pattern, &handler)
+          @routes << [method.to_s.upcase, pattern, handler]
+          self
+        end
+
+        # Answers matching requests with a fixed status and body.
+        def stub(method, pattern, status:, body:)
+          route(method, pattern) { Response.new(status: status, body: body) }
+        end
+
+        def session(client_secret: @client_secret, **kwargs)
+          Session.new(@client_id, client_secret, base_url: BASE_URL, transport: self, **kwargs)
+        end
+
+        def revoke_tokens = @tokens.clear
+
+        def perform(request)
+          @requests << request
+          path = URI(request["url"]).path
+          return token_response(request) if path.end_with?(TOKEN_PATH)
+          return Response.new(status: 401, body: "Access Token in the request, identified by HEADER access_token, is invalid.") unless authorized?(request)
+
+          @routes.each do |method, pattern, handler|
+            next unless request["method"] == method && (match = pattern.match(path))
+
+            return handler.call(request, match)
+          end
+          Response.new(status: 404, body: JSON.generate({ "success" => false, "message" => "Not found", "errors" => [] }))
+        end
+
+        def close; end
+
+        private
+
+        def token_response(request)
+          @token_requests += 1
+          expected = "Basic #{["#{@client_id}:#{@client_secret}"].pack("m0")}"
+          unless request["headers"]["Authorization"] == expected
+            return Response.new(status: 401, body: JSON.generate({ "error" => "invalid_client", "error_description" => "Bad credentials" }))
+          end
+
+          token = SecureRandom.uuid
+          @tokens << token
+          # Sandbox answers 201 with token_type "access_token" and no scope.
+          Response.new(status: 201, body: JSON.generate({ "access_token" => token, "token_type" => "access_token", "expires_in" => @token_ttl }))
+        end
+
+        def authorized?(request)
+          @tokens.include?(request["headers"]["access_token"]) && request["headers"]["client_id"] == @client_id
+        end
+      end
+    end
+  end
+end

data/lib/openhub_bo/core/transport.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module OpenhubBo
+  module Core
+    Response = Data.define(:status, :body) do
+      def to_wire = { "status" => status, "body" => body }
+    end
+
+    # Sends requests built by the native core. Any object responding to
+    # `perform(request) -> Response` works: inject your own for proxies,
+    # logging or fakes. `request` is {"method", "url", "headers", "body",
+    # "timeout"?}; raise TransportError on network failures.
+    class NetHttpTransport
+      # Failures where the request provably never reached the server.
+      NOT_SENT = [
+        Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Net::OpenTimeout, SocketError
+      ].freeze
+      MAYBE_SENT = [
+        Net::ReadTimeout, Net::WriteTimeout, EOFError, IOError, Errno::ECONNRESET, Errno::EPIPE,
+        OpenSSL::SSL::SSLError
+      ].freeze
+
+      def initialize(timeout: 30, open_timeout: 10)
+        @timeout = timeout
+        @open_timeout = open_timeout
+      end
+
+      def perform(request)
+        uri = URI(request["url"])
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = request["timeout"] || @timeout
+        http.write_timeout = request["timeout"] || @timeout
+        body = request["body"]
+        message = Net::HTTPGenericRequest.new(
+          request["method"], !body.nil?, true, uri.request_uri, request["headers"]
+        )
+        message.body = body if body
+        response = http.start { |conn| conn.request(message) }
+        Response.new(status: response.code.to_i, body: response.body.to_s.dup.force_encoding(Encoding::UTF_8))
+      rescue *NOT_SENT => e
+        raise TransportError.new("#{e.class}: #{e.message}", maybe_sent: false)
+      rescue *MAYBE_SENT => e
+        raise TransportError.new("#{e.class}: #{e.message}", maybe_sent: true)
+      end
+
+      def close; end
+    end
+  end
+end

data/lib/openhub_bo/core/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OpenhubBo
+  module Core
+    VERSION = "0.1.0"
+    # Core FFI protocol this Ruby code speaks (see `openhub_bo_core::ffi`).
+    SUPPORTED_PROTOCOL = 2
+  end
+end

data/lib/openhub_bo/core.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Shared foundation of the openhub-bo gems: session, transport, errors and
+# common types for the Red Enlace (ATC) OpenHub APIs.
+require "bigdecimal"
+require "json"
+
+require_relative "core/version"
+require_relative "core/errors"
+require_relative "core/models"
+require_relative "core/native_bridge"
+require_relative "core/op"
+require_relative "core/transport"
+begin
+  # Precompiled gems ship one binary per Ruby minor version.
+  require "openhub_bo/core/#{RUBY_VERSION[/\d+\.\d+/]}/openhub_bo_core"
+rescue LoadError
+  require "openhub_bo/core/openhub_bo_core"
+end
+require_relative "core/session"