lipwa 0.1.1

data/lib/lipwa/gateway.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require_relative "errors"
+require_relative "types"
+require_relative "capability"
+require_relative "auth_strategies"
+require_relative "http_adapter"
+require_relative "configuration"
+
+module Lipwa
+  # Abstract base every provider gateway (Mpesa, CoopBank, Jenga, ...)
+  # inherits from. Holds the gateway's Dry::Configurable settings, lazily
+  # builds the shared HttpAdapter from them, and answers `capability?`
+  # by checking which Lipwa::Capabilities::* modules the subclass
+  # actually included — see Lipwa::Capability.
+  class Gateway
+    extend Dry::Configurable
+
+    setting :env, default: :sandbox, constructor: Types::Environment
+    setting :base_url
+    setting :timeout
+    setting :open_timeout, default: 5
+    setting :logger
+    setting :auth_strategy
+
+    class << self
+      def capabilities
+        @capabilities ||= Set.new
+      end
+
+      # Called by Lipwa::Capability#included — not meant to be called
+      # directly.
+      def register_capability(name)
+        capabilities << name.to_sym
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@capabilities, capabilities.dup)
+      end
+    end
+
+    def capability?(name)
+      self.class.capabilities.include?(name.to_sym)
+    end
+
+    def http
+      @http ||= build_http_adapter
+    end
+
+    private
+
+    def build_http_adapter
+      config = self.class.config
+      ensure_base_url_configured!(config)
+
+      HttpAdapter.new(
+        base_url: config.base_url,
+        auth_strategy: config.auth_strategy || AuthStrategies::None.new,
+        timeout: config.timeout || Lipwa.config.default_timeout,
+        open_timeout: config.open_timeout,
+        logger: config.logger || Lipwa.config.logger,
+        adapter: Lipwa.config.adapter
+      )
+    end
+
+    def ensure_base_url_configured!(config)
+      return if config.base_url
+
+      raise Lipwa::ConfigurationError, "#{self.class} is missing `base_url` — set it via .configure"
+    end
+  end
+end

data/lib/lipwa/gateways/mpesa/auth.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "base64"
+require_relative "../../errors"
+require_relative "../../http_adapter"
+
+module Lipwa
+  module Gateways
+    class Mpesa
+      # OAuth2 client-credentials token acquisition + caching for
+      # Safaricom Daraja. Exposes #call so an instance can be handed
+      # directly to Lipwa::AuthStrategies::BearerToken as its
+      # token_provider: the STK Push/C2B/B2C HttpAdapter calls #call on
+      # every request, and gets back a cached token until it's close to
+      # expiring, at which point a fresh one is fetched transparently.
+      #
+      # The token endpoint itself authenticates with HTTP Basic auth
+      # (consumer_key:consumer_secret) rather than a bearer token, so
+      # this class talks to it directly instead of going through
+      # AuthStrategies.
+      class Auth
+        BASE_URLS = {
+          sandbox: "https://sandbox.safaricom.co.ke",
+          production: "https://api.safaricom.co.ke"
+        }.freeze
+
+        OAUTH_PATH = "/oauth/v1/generate"
+
+        # Refresh this many seconds before the token's reported expiry,
+        # so a request that starts just before expiry doesn't race a
+        # token that goes stale mid-flight.
+        EXPIRY_BUFFER = 60
+
+        def initialize(consumer_key:, consumer_secret:, env: :sandbox, http: nil, clock: -> { Time.now })
+          ensure_credentials_present!(consumer_key, consumer_secret)
+
+          @consumer_key = consumer_key
+          @consumer_secret = consumer_secret
+          @clock = clock
+          @http = http || Lipwa::HttpAdapter.new(base_url: base_url_for(env))
+          @mutex = Mutex.new
+          @token = nil
+          @expires_at = nil
+        end
+
+        # Returns a cached access token, or fetches (and caches) a new
+        # one if there's none yet or the cached one is about to expire.
+        # Safe to call concurrently: only one refresh happens in flight,
+        # other callers block on it and reuse its result.
+        def call
+          return @token if fresh?
+
+          @mutex.synchronize do
+            refresh! unless fresh?
+          end
+
+          @token
+        end
+
+        private
+
+        def fresh?
+          @token && @expires_at && @clock.call < @expires_at
+        end
+
+        def refresh!
+          response = @http.get(
+            OAUTH_PATH,
+            params: { grant_type: "client_credentials" },
+            headers: { "Authorization" => "Basic #{encoded_credentials}" }
+          )
+          body = response.body
+
+          @token = body.fetch("access_token")
+          @expires_at = @clock.call + body.fetch("expires_in").to_i - EXPIRY_BUFFER
+        rescue KeyError
+          raise Lipwa::GatewayError.new("unexpected Daraja OAuth response: #{body.inspect}", raw: body)
+        end
+
+        def encoded_credentials
+          Base64.strict_encode64("#{@consumer_key}:#{@consumer_secret}")
+        end
+
+        def base_url_for(env)
+          BASE_URLS.fetch(env.to_sym) do
+            raise Lipwa::ConfigurationError, "unknown M-Pesa env #{env.inspect} — must be :sandbox or :production"
+          end
+        end
+
+        def ensure_credentials_present!(consumer_key, consumer_secret)
+          return if consumer_key && consumer_secret
+
+          raise Lipwa::ConfigurationError, "Mpesa::Auth requires both consumer_key and consumer_secret"
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/gateways/mpesa/security_credential.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require_relative "../../errors"
+
+module Lipwa
+  module Gateways
+    class Mpesa
+      # Encrypts the B2C/B2B initiator password into the SecurityCredential
+      # Daraja expects: RSA-encrypted (PKCS#1 v1.5 padding) with Safaricom's
+      # public certificate, then base64-encoded. Sandbox and production use
+      # different certificates — download the right one from the Daraja
+      # portal (Test Credentials page for sandbox, the app's production
+      # cert for production) and pass its PEM/DER content as
+      # `security_credential_cert:` on the Mpesa gateway config. Daraja is
+      # the only party that ever decrypts this, so there's nothing to
+      # verify locally beyond "does this cert parse and encrypt".
+      module SecurityCredential
+        def self.encrypt(password, cert:)
+          certificate = OpenSSL::X509::Certificate.new(cert)
+          encrypted = certificate.public_key.public_encrypt(password, OpenSSL::PKey::RSA::PKCS1_PADDING)
+          Base64.strict_encode64(encrypted)
+        rescue OpenSSL::X509::CertificateError, OpenSSL::PKey::PKeyError => e
+          raise Lipwa::ConfigurationError, "invalid security_credential_cert: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/lipwa/gateways/mpesa.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../gateway"
+require_relative "../gateways"
+require_relative "../capabilities/c2b"
+require_relative "../capabilities/stk_push"
+require_relative "../capabilities/disbursement"
+require_relative "../capabilities/status_query"
+require_relative "../capabilities/refund"
+
+module Lipwa
+  module Gateways
+    # Safaricom Daraja gateway. base_url and auth_strategy are derived
+    # automatically from env/consumer_key/consumer_secret rather than set
+    # directly, since Daraja's OAuth + sandbox/production hosts are fixed
+    # per environment.
+    class Mpesa < Lipwa::Gateway
+      include Lipwa::Capabilities::C2B
+      include Lipwa::Capabilities::StkPush
+      include Lipwa::Capabilities::Disbursement
+      include Lipwa::Capabilities::StatusQuery
+      include Lipwa::Capabilities::Refund
+
+      setting :consumer_key
+      setting :consumer_secret
+      setting :shortcode
+      setting :passkey
+      setting :initiator_name
+      setting :initiator_password
+      setting :security_credential_cert
+
+      private
+
+      def build_http_adapter
+        config = self.class.config
+        ensure_mpesa_config_present!(config)
+
+        HttpAdapter.new(**http_adapter_options(config))
+      end
+
+      def http_adapter_options(config)
+        {
+          base_url: Auth::BASE_URLS.fetch(config.env),
+          auth_strategy: AuthStrategies::BearerToken.new(build_auth(config)),
+          timeout: config.timeout || Lipwa.config.default_timeout,
+          open_timeout: config.open_timeout,
+          logger: config.logger || Lipwa.config.logger,
+          adapter: Lipwa.config.adapter
+        }
+      end
+
+      def build_auth(config)
+        Auth.new(consumer_key: config.consumer_key, consumer_secret: config.consumer_secret, env: config.env)
+      end
+
+      def ensure_mpesa_config_present!(config)
+        return if config.consumer_key && config.consumer_secret && config.shortcode && config.passkey
+
+        raise Lipwa::ConfigurationError,
+              "#{self.class} is missing consumer_key/consumer_secret/shortcode/passkey — set them via .configure"
+      end
+    end
+  end
+end
+
+require_relative "mpesa/auth"
+require_relative "mpesa/security_credential"
+
+Lipwa::Gateways.register(:mpesa, Lipwa::Gateways::Mpesa)

data/lib/lipwa/gateways.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "dry/container"
+require_relative "errors"
+require_relative "gateway"
+
+module Lipwa
+  # Dry::Container-based registry of provider gateways. Providers register
+  # their Gateway subclass once (typically at load time); consumers look
+  # them up by name instead of hardcoding gateway class names — see
+  # Lipwa.gateway.
+  module Gateways
+    extend Dry::Container::Mixin
+
+    class << self
+      def register(key, gateway_class)
+        unless gateway_class.is_a?(Class) && gateway_class <= Lipwa::Gateway
+          raise Lipwa::ConfigurationError, "#{gateway_class} must be a subclass of Lipwa::Gateway"
+        end
+
+        super(key.to_sym, memoize: true) { gateway_class.new }
+      end
+    end
+  end
+end

data/lib/lipwa/http_adapter.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require_relative "errors"
+require_relative "auth_strategies"
+
+module Lipwa
+  # Thin wrapper around Faraday shared by every gateway's HTTP calls:
+  # retries with backoff, request/open timeouts, optional logging, and
+  # a pluggable auth strategy (see Lipwa::AuthStrategies) so OAuth2
+  # bearer tokens (M-Pesa, Co-op) and request-signing (Jenga) plug into
+  # the same request path without HttpAdapter knowing which is which.
+  class HttpAdapter
+    DEFAULT_RETRY_OPTIONS = {
+      max: 2,
+      interval: 0.5,
+      interval_randomness: 0.5,
+      backoff_factor: 2,
+      retry_statuses: [429, 500, 502, 503, 504],
+      methods: %i[get post put patch delete],
+      exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS
+    }.freeze
+
+    attr_reader :base_url, :auth_strategy, :timeout, :open_timeout, :logger, :adapter
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(base_url:, auth_strategy: AuthStrategies::None.new, timeout: 10,
+                   open_timeout: 5, logger: nil, retry_options: {}, stubs: nil,
+                   adapter: Faraday.default_adapter)
+      @base_url = base_url
+      @auth_strategy = auth_strategy
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @logger = logger
+      @retry_options = DEFAULT_RETRY_OPTIONS.merge(retry_options)
+      @stubs = stubs
+      @adapter = adapter
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def get(path, params: {}, headers: {})
+      request(:get, path, params: params, headers: headers)
+    end
+
+    def post(path, body: nil, params: {}, headers: {})
+      request(:post, path, body: body, params: params, headers: headers)
+    end
+
+    def put(path, body: nil, params: {}, headers: {})
+      request(:put, path, body: body, params: params, headers: headers)
+    end
+
+    private
+
+    def request(method, path, params: {}, body: nil, headers: {})
+      connection.public_send(method) { |req| build_request(req, path, params, body, headers) }
+    rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      raise Lipwa::GatewayError.new("network error: #{e.message}", raw: e)
+    rescue Faraday::Error => e
+      raise Lipwa::GatewayError.new(e.message, code: e.response&.dig(:status)&.to_s, raw: e.response)
+    end
+
+    def build_request(req, path, params, body, headers)
+      req.url(path)
+      req.params.update(params) if params && !params.empty?
+      req.headers.update(headers)
+      req.body = body if body
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |conn|
+        configure_middleware(conn)
+        configure_timeouts(conn)
+        @stubs ? conn.adapter(:test, @stubs) : conn.adapter(@adapter)
+      end
+    end
+
+    def configure_middleware(conn)
+      conn.request :retry, @retry_options
+      conn.request :json
+      conn.response :json, content_type: /\bjson$/
+      configure_logger(conn) if logger
+      conn.use AuthMiddleware, auth_strategy
+    end
+
+    def configure_logger(conn)
+      conn.response :logger, logger, headers: true, bodies: true do |l|
+        l.filter(/(Authorization: )(.+)/, '\1[REDACTED]')
+      end
+    end
+
+    def configure_timeouts(conn)
+      conn.options.timeout = timeout
+      conn.options.open_timeout = open_timeout
+    end
+
+    # Applies the configured AuthStrategy on every outgoing request.
+    class AuthMiddleware < Faraday::Middleware
+      def initialize(app, auth_strategy)
+        super(app)
+        @auth_strategy = auth_strategy
+      end
+
+      def on_request(env)
+        @auth_strategy.apply(env)
+      end
+    end
+  end
+end

data/lib/lipwa/money.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+require_relative "types"
+
+module Lipwa
+  # Immutable representation of an amount in minor currency units.
+  # KES has no subunit in practice, but we keep minor units as the
+  # storage form so other currencies fit the same shape later.
+  class Money < Dry::Struct
+    attribute :amount, Types::Amount
+    attribute :currency, Types::Currency.default("KES")
+
+    def +(other)
+      assert_same_currency!(other)
+      self.class.new(amount: amount + other.amount, currency: currency)
+    end
+
+    def -(other)
+      assert_same_currency!(other)
+      self.class.new(amount: amount - other.amount, currency: currency)
+    end
+
+    def to_s
+      "#{amount} #{currency}"
+    end
+
+    private
+
+    def assert_same_currency!(other)
+      return if currency == other.currency
+
+      raise ArgumentError, "currency mismatch: #{currency} vs #{other.currency}"
+    end
+  end
+end

data/lib/lipwa/response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+require_relative "types"
+
+module Lipwa
+  # Normalized result of a successful gateway call. Provider-specific
+  # payloads stay available via `raw` for anything the common shape
+  # doesn't capture.
+  class Response < Dry::Struct
+    attribute :success, Types::Strict::Bool
+    attribute :provider_reference, Types::Strict::String.optional
+    attribute :message, Types::Strict::String.optional.default(nil)
+    attribute :code, Types::Strict::String.optional.default(nil)
+    attribute :raw, Types::Any.default(nil)
+
+    def success?
+      success
+    end
+  end
+end

data/lib/lipwa/types.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "dry/types"
+
+module Lipwa
+  # Shared Dry::Types module for value objects across the gem.
+  module Types
+    include Dry.Types()
+
+    # Amounts are always integers in minor currency units (e.g. cents,
+    # or whole KES since M-Pesa has no subunit) to avoid float math.
+    Amount = Types::Strict::Integer.constrained(gteq: 0)
+
+    Currency = Types::Strict::String.constrained(format: /\A[A-Z]{3}\z/)
+
+    Environment = Types::Strict::Symbol.enum(:sandbox, :production)
+  end
+end

data/lib/lipwa/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lipwa
+  VERSION = "0.1.1"
+end

data/lib/lipwa/webhook.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "dry/container"
+require "dry/monads"
+require "json"
+require_relative "errors"
+
+module Lipwa
+  # Normalized inbound-webhook event produced by Lipwa::Webhook.parse_webhook.
+  # `verify_signature` is bound to a provider-specific verifier at parse
+  # time, so callers get one uniform API regardless of how a given
+  # provider actually authenticates its callbacks (M-Pesa has no
+  # cryptographic signature, so it checks the request's source IP
+  # against Safaricom's published ranges; a provider that does sign
+  # payloads can verify an HMAC/header instead — see Lipwa::Webhooks::Mpesa).
+  class WebhookEvent
+    attr_reader :provider, :event_type, :provider_reference, :message, :raw
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(provider:, event_type:, raw:, success: nil, provider_reference: nil, message: nil, verifier: nil)
+      @provider = provider
+      @event_type = event_type
+      @raw = raw
+      @success = success
+      @provider_reference = provider_reference
+      @message = message
+      @verifier = verifier
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def success?
+      !!@success
+    end
+
+    # kwargs are provider-specific (e.g. `source_ip:` for M-Pesa,
+    # `secret:`/`signature_header:` for an HMAC-based provider) — a
+    # given verifier only looks at the ones it understands.
+    def verify_signature(**opts)
+      raise Lipwa::ConfigurationError, "#{provider} has no signature verifier registered" unless @verifier
+
+      @verifier.call(raw: raw, **opts)
+    end
+  end
+
+  # Inbound-callback parsing/verification, pluggable per provider.
+  # Providers register a parser once (typically at load time — see
+  # Lipwa::Webhooks::Mpesa); consumers call Lipwa::Webhook.parse_webhook
+  # instead of hand-rolling per-provider payload parsing in their
+  # controllers.
+  module Webhook
+    extend Dry::Container::Mixin
+    extend Dry::Monads[:result]
+
+    class << self
+      def register(provider, parser)
+        super(provider.to_sym, parser)
+      end
+
+      def parse_webhook(provider:, body:, headers: {})
+        Success(resolve(provider.to_sym).call(body: body, headers: headers))
+      rescue Dry::Container::KeyError
+        raise Lipwa::UnsupportedProviderError, "no webhook parser registered for #{provider.inspect}"
+      rescue JSON::ParserError => e
+        Failure(Lipwa::WebhookParseError.new(e.message))
+      end
+    end
+  end
+end

data/lib/lipwa/webhooks/mpesa.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "../webhook"
+
+module Lipwa
+  module Webhooks
+    # Parses Daraja's distinct callback shapes into a normalized
+    # Lipwa::WebhookEvent:
+    #
+    #   * STK Push result callback — {"Body"=>{"stkCallback"=>{...}}}
+    #   * Transaction Status / Disbursement result callback —
+    #     {"Result"=>{...}}, delivered to the ResultURL given to
+    #     Lipwa::Capabilities::StatusQuery#status (and B2C/B2B) once
+    #     Daraja finishes processing the query.
+    #   * C2B validation/confirmation — a flat hash (TransID, MSISDN, ...),
+    #     wire-identical for both requests. Daraja's only signal for which
+    #     one fired is which registered URL it hit, not the payload, so
+    #     both are normalized as :c2b — callers that registered distinct
+    #     validation/confirmation URLs already know which is which.
+    #
+    # Daraja does not sign callbacks with any HMAC/shared secret, so
+    # #verify_signature checks the request's source IP against
+    # Safaricom's published callback IP ranges instead of a
+    # cryptographic signature.
+    module Mpesa
+      # Safaricom's published source IPs for STK/C2B callbacks
+      # (https://developer.safaricom.co.ke/docs, "Callback IP Addresses").
+      TRUSTED_IPS = %w[
+        196.201.214.200 196.201.214.206 196.201.213.114 196.201.214.207
+        196.201.214.208 196.201.213.44 196.201.212.127 196.201.212.138
+        196.201.212.129 196.201.212.136 196.201.212.74 196.201.212.69
+      ].freeze
+
+      module_function
+
+      def call(body:, headers: {}) # rubocop:disable Lint/UnusedMethodArgument
+        payload = parse(body)
+        stk = payload["Body"]&.fetch("stkCallback", nil)
+        result = payload["Result"]
+
+        return stk_event(stk) if stk
+        return transaction_status_event(result) if result
+
+        c2b_event(payload)
+      end
+
+      def parse(body)
+        body.is_a?(String) ? JSON.parse(body) : body
+      end
+
+      def stk_event(stk)
+        Lipwa::WebhookEvent.new(
+          provider: :mpesa,
+          event_type: :stk_callback,
+          success: stk["ResultCode"].zero?,
+          provider_reference: stk["CheckoutRequestID"],
+          message: stk["ResultDesc"],
+          raw: stk,
+          verifier: method(:verify_signature)
+        )
+      end
+
+      def transaction_status_event(result)
+        Lipwa::WebhookEvent.new(
+          provider: :mpesa,
+          event_type: :transaction_status,
+          success: result["ResultCode"].zero?,
+          provider_reference: result["TransactionID"] || result["ConversationID"],
+          message: result["ResultDesc"],
+          raw: result,
+          verifier: method(:verify_signature)
+        )
+      end
+
+      # C2B callbacks only fire for an already-completed paybill/till
+      # payment — there is no ResultCode to key off, so `success` is
+      # unconditionally true. Accepting or rejecting the underlying
+      # transaction is the app's own response to the validation request,
+      # not something reflected in this event.
+      def c2b_event(payload)
+        Lipwa::WebhookEvent.new(
+          provider: :mpesa,
+          event_type: :c2b,
+          success: true,
+          provider_reference: payload["TransID"],
+          message: nil,
+          raw: payload,
+          verifier: method(:verify_signature)
+        )
+      end
+
+      def verify_signature(raw:, source_ip: nil, **) # rubocop:disable Lint/UnusedMethodArgument
+        return false unless source_ip
+
+        TRUSTED_IPS.include?(source_ip)
+      end
+    end
+  end
+end
+
+Lipwa::Webhook.register(:mpesa, Lipwa::Webhooks::Mpesa)