lunixi-sdk 0.1.2

data/lib/lunixi/errors.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lunixi
+  # Errors deliberately omit response bodies, request bodies and credentials.
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class SignatureError < Error; end
+  class WebhookError < Error; end
+  class ReplayConflict < WebhookError; end
+  class TransportError < Error; end
+  class RedirectError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :code, :request_id, :retry_after
+
+    def initialize(status:, code: nil, request_id: nil, retry_after: nil)
+      @status = status
+      @code = safe_identifier(code)
+      @request_id = safe_identifier(request_id)
+      @retry_after = retry_after
+      super("Lunixi request failed (HTTP #{status})")
+    end
+
+    private
+
+    def safe_identifier(value)
+      value if value.is_a?(String) && value.match?(/\A[a-zA-Z0-9_.:-]{1,200}\z/)
+    end
+  end
+
+  class AuthenticationError < ApiError; end
+  class ValidationError < ApiError; end
+  class RateLimitError < ApiError; end
+end

data/lib/lunixi/fraud.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lunixi
+  class Fraud
+    FIELDS = %w[integrationMode productContext transactionRef channel surface stage operationKind authModeRequested
+                authModeApplied subMerchantRef subjectType subjectId paymentRail transferDirection merchantGroupIds
+                paymentId payment bankTransfer cryptoTransfer walletOperation billPayment loanApplication payout
+                customer device session merchant mobileApp telemetry metadata identitySnapshot identityAssertion].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Evaluate the documented fraud DTO; tenant identity comes from credentials.
+    def evaluate(body)
+      raise ConfigurationError, 'Fraud request must be an object' unless body.is_a?(Hash)
+
+      data = JSON.parse(JsonBody.dump(body))
+      raise ConfigurationError, 'Fraud request contains an unknown root field' unless (data.keys - FIELDS).empty?
+
+      @client.request('POST', '/api/v1/fraud/decisions/evaluate', body: data, signed: false)
+    end
+
+    # Record a signed transaction event with a persisted operation idempotency key.
+    def record_event(body, idempotency_key:)
+      unless body.is_a?(Hash) && %w[eventId subjectType eventType occurredAt].all? { |name| body[name] || body[name.to_sym] }
+        raise ConfigurationError, 'Fraud event requires eventId, subjectType, eventType and occurredAt'
+      end
+
+      @client.request('POST', '/api/v1/fraud/events/transactions', body: body,
+                                                                   idempotency_key: Client.idempotency_key!(idempotency_key))
+    end
+  end
+end

data/lib/lunixi/json_body.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Lunixi
+  # JSON bytes compatible with JSON.parse followed by JSON.stringify at the gateway.
+  # Ruby hashes preserve insertion order; JavaScript moves array-index keys first.
+  module JsonBody
+    MAX_SAFE_INTEGER = 9_007_199_254_740_991
+    MAX_DEPTH = 64
+
+    module_function
+
+    def dump(value)
+      encode(value, 0).freeze
+    rescue JSON::GeneratorError, EncodingError
+      raise ConfigurationError, 'Request contains invalid JSON text', cause: nil
+    end
+
+    def encode(value, depth)
+      raise ConfigurationError, 'Request JSON nesting is too deep' if depth > MAX_DEPTH
+
+      case value
+      when Hash then encode_hash(value, depth)
+      when Array then "[#{value.map { |entry| encode(entry, depth + 1) }.join(',')}]"
+      when String
+        utf8 = value.encode(Encoding::UTF_8)
+        raise ConfigurationError, 'Request contains invalid UTF-8' unless utf8.valid_encoding?
+
+        JSON.generate(utf8)
+      when Integer
+        raise ConfigurationError, 'JSON integer exceeds the JavaScript safe range; use a documented digit-string field' if value.abs > MAX_SAFE_INTEGER
+
+        value.to_s
+      when Float then float_number(value)
+      when true then 'true'
+      when false then 'false'
+      when nil then 'null'
+      else raise ConfigurationError, 'Request contains an unsupported JSON value'
+      end
+    end
+
+    def encode_hash(value, depth)
+      pairs = {}
+      value.each do |key, entry|
+        raise ConfigurationError, 'JSON object keys must be strings or symbols' unless key.is_a?(String) || key.is_a?(Symbol)
+
+        name = key.to_s
+        raise ConfigurationError, 'Duplicate normalized JSON key' if pairs.key?(name)
+
+        pairs[name] = entry
+      end
+      indexed, ordinary = pairs.keys.partition { |key| array_index?(key) }
+      ordered = indexed.sort_by(&:to_i) + ordinary
+      "{#{ordered.map { |key| "#{encode(key, depth + 1)}:#{encode(pairs.fetch(key), depth + 1)}" }.join(',')}}"
+    end
+
+    def array_index?(key)
+      key.match?(/\A(?:0|[1-9][0-9]{0,9})\z/) && key.to_i < 4_294_967_295
+    end
+
+    # Both runtimes use the shortest round-trippable decimal. ECMAScript expands
+    # values in [1e-6, 1e21) and writes the exponent without leading zeroes.
+    def float_number(value)
+      raise ConfigurationError, 'JSON numbers must be finite' unless value.finite?
+      return '0' if value.zero?
+
+      sign = value.negative? ? '-' : ''
+      mantissa, exponent = value.abs.to_s.downcase.split('e')
+      exponent = exponent ? exponent.to_i : 0
+      integer, fraction = mantissa.split('.')
+      fraction = (fraction || '').sub(/0+\z/, '')
+      digits = integer + fraction
+      point = integer.length + exponent
+      number = if value.abs >= 1e-6 && value.abs < 1e21
+                 fixed_number(digits, point)
+               else
+                 scientific_number(digits, point, integer, exponent, mantissa)
+               end
+      sign + number
+    end
+
+    def fixed_number(digits, point)
+      if point <= 0
+        "0.#{'0' * -point}#{digits}"
+      elsif point >= digits.length
+        digits + ('0' * (point - digits.length))
+      else
+        "#{digits[0...point]}.#{digits[point..]}"
+      end
+    end
+
+    def scientific_number(digits, point, integer, exponent, mantissa)
+      significant = digits.sub(/\A0+/, '')
+      decimal_exponent = point - integer.index(/[1-9]/).to_i - 1
+      # Scientific Ruby output has one digit before the decimal point.
+      decimal_exponent = exponent if mantissa.to_f >= 1 && mantissa.to_f < 10
+      coefficient = significant[0] + (significant.length > 1 ? ".#{significant[1..]}" : '')
+      exponent_text = decimal_exponent.negative? ? decimal_exponent.to_s : "+#{decimal_exponent}"
+      "#{coefficient}e#{exponent_text}"
+    end
+  end
+end

data/lib/lunixi/payments.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Lunixi
+  # Explicit payment routes. The advanced Client#request method covers other
+  # documented endpoints without pretending to validate their entire DTO schema.
+  class Payments
+    BASE = '/api/v1/payments'
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Create hosted/embedded checkout using integer minor units and a durable attempt key.
+    # @return [Hash] Unmodified gateway response envelope; creation is not settlement.
+    def create_intent(body, idempotency_key:)
+      body = payment_body!(body)
+      raise ConfigurationError, 'Intent installments are selected in the checkout form' if body.key?('installment')
+
+      client.request('POST', "#{BASE}/intents", body: body, idempotency_key: Client.idempotency_key!(idempotency_key))
+    end
+
+    # @return [Hash] Authenticated payment status envelope for reconciliation.
+    def get(payment_id)
+      client.request('GET', "#{BASE}/#{identifier!(payment_id)}", signed: false)
+    end
+
+    # @param filters [Hash] Documented gateway payment list query fields.
+    def list(**filters)
+      client.request('GET', BASE, query: filters, signed: false)
+    end
+
+    # Return merchant-enabled methods; the shared Lunixi form owns the final available list.
+    def methods(payment_method: nil)
+      query = payment_method ? { paymentMethod: payment_method } : {}
+      client.request('GET', "#{BASE}/methods", query: query)
+    end
+
+    # Capture an authorization; nil amount requests the gateway's remaining amount.
+    def capture(payment_id, idempotency_key:, amount: nil)
+      body = { 'paymentIntentId' => identifier!(payment_id) }
+      body['amount'] = minor!(amount) unless amount.nil?
+      client.request('POST', "#{BASE}/#{payment_id}/capture", body: body, idempotency_key: Client.idempotency_key!(idempotency_key))
+    end
+
+    # Refund captured funds; persist a separate key for each refund operation.
+    def refund(payment_id, idempotency_key:, amount: nil, reason: nil)
+      body = { 'paymentIntentId' => identifier!(payment_id) }
+      body['amount'] = minor!(amount) unless amount.nil?
+      body['reason'] = reason!(reason) unless reason.nil?
+      client.request('POST', "#{BASE}/#{payment_id}/refund", body: body, idempotency_key: Client.idempotency_key!(idempotency_key))
+    end
+
+    # Void an authorization without inventing a settlement success result.
+    def void(payment_id, idempotency_key:)
+      client.request('POST', "#{BASE}/#{identifier!(payment_id)}/void", idempotency_key: Client.idempotency_key!(idempotency_key))
+    end
+
+    # Start a 1–5 leg split payment; running statuses are returned, never marked paid.
+    def split(body, idempotency_key:)
+      data = normalize!(body)
+      minor!(data['totalAmount'])
+      currency!(data['currency'])
+      text!(data['ownerRef'])
+      legs = data['legs']
+      raise ConfigurationError, 'Split payment requires 1–5 legs' unless legs.is_a?(Array) && legs.size.between?(1, 5)
+
+      total = legs.sum do |leg|
+        raise ConfigurationError, 'Split legs must be objects' unless leg.is_a?(Hash)
+
+        minor!(leg['amount'])
+      end
+      raise ConfigurationError, 'Split leg amounts must equal totalAmount' unless total == data['totalAmount']
+
+      client.request('POST', "#{BASE}/split", body: data, idempotency_key: Client.idempotency_key!(idempotency_key))
+    end
+
+    # @return [Hash] Current split-session status envelope.
+    def get_split(split_id)
+      client.request('GET', "#{BASE}/split/#{identifier!(split_id)}", signed: false)
+    end
+
+    # Refund a split session using the documented partial/full amount in minor units.
+    def refund_split(split_id, amount:, idempotency_key:, reason: nil)
+      body = { 'amount' => minor!(amount) }
+      body['reason'] = reason!(reason) unless reason.nil?
+      client.request('POST', "#{BASE}/split/#{identifier!(split_id)}/refund", body: body,
+                                                                              idempotency_key: Client.idempotency_key!(idempotency_key))
+    end
+
+    private
+
+    def identifier!(value)
+      raise ConfigurationError, 'Invalid resource identifier' unless value.is_a?(String) && value.match?(/\A[a-zA-Z0-9_-]{1,256}\z/)
+
+      value
+    end
+
+    def minor!(value)
+      unless value.is_a?(Integer) && value.positive? && value <= JsonBody::MAX_SAFE_INTEGER
+        raise ConfigurationError, 'Amount must be a positive safe integer in minor units'
+      end
+
+      value
+    end
+
+    def currency!(value)
+      raise ConfigurationError, 'Currency must be a three-letter uppercase code' unless value.is_a?(String) && value.match?(/\A[A-Z]{3}\z/)
+    end
+
+    def reason!(value)
+      raise ConfigurationError, 'Reason must be a string of at most 500 characters' unless value.is_a?(String) && value.size <= 500
+
+      value
+    end
+
+    def text!(value)
+      unless value.is_a?(String) && !value.strip.empty? && value.bytesize <= 255 && !value.match?(/[\x00-\x1f\x7f]/)
+        raise ConfigurationError, 'Reference must be a bounded nonempty string'
+      end
+
+      value
+    end
+
+    def normalize!(body)
+      raise ConfigurationError, 'Payment body must be an object' unless body.is_a?(Hash)
+
+      JSON.parse(JsonBody.dump(body))
+    end
+
+    def payment_body!(body)
+      data = normalize!(body)
+      raise ConfigurationError, 'Removed amount field; use amount in integer minor units' if %w[price paidPrice].any? { |key| data.key?(key) }
+
+      minor!(data['amount'])
+      currency!(data['currency'])
+      text!(data['orderId'])
+      validate_callback!(data['callbackUrl']) if data.key?('callbackUrl')
+      raise ConfigurationError, 'preauth must be a JSON boolean' if data.key?('preauth') && ![true, false].include?(data['preauth'])
+
+      validate_basket!(data['basketItems'], data['amount']) if data.key?('basketItems')
+      data
+    end
+
+    def validate_callback!(url)
+      uri = URI.parse(url)
+      raise ConfigurationError, 'callbackUrl must use HTTPS' unless uri.is_a?(URI::HTTPS) && uri.host && !uri.userinfo && !uri.fragment && url.bytesize <= 2048
+    rescue URI::InvalidURIError, TypeError
+      raise ConfigurationError, 'Invalid callbackUrl', cause: nil
+    end
+
+    def validate_basket!(items, amount)
+      raise ConfigurationError, 'basketItems must be a nonempty array' unless items.is_a?(Array) && !items.empty?
+
+      total = items.sum do |item|
+        raise ConfigurationError, 'Basket items must be objects' unless item.is_a?(Hash)
+
+        minor!(item['price'])
+      end
+      raise ConfigurationError, 'Basket total must equal amount' unless total == amount
+    end
+  end
+end

data/lib/lunixi/signer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+require 'digest'
+
+module Lunixi
+  # Uses OpenSSL's Ed25519 implementation; no curve arithmetic is implemented here.
+  class Signer
+    PREFIX = ['302e020100300506032b657004220420'].pack('H*').freeze
+
+    def initialize(private_key)
+      raise ConfigurationError, 'An Ed25519 private key is required' unless private_key.is_a?(String) && !private_key.strip.empty?
+
+      material = private_key.strip
+      unless material.include?('-----BEGIN')
+        raw = Base64.strict_decode64(material)
+        raw = PREFIX + raw[0, 32] if [32, 64].include?(raw.bytesize)
+        material = raw
+      end
+      @key = OpenSSL::PKey.read(material)
+      raise ConfigurationError, 'Only Ed25519 private keys are accepted' unless @key.oid == 'ED25519'
+
+      @key.sign(nil, 'key-check') # Reject public-only keys at construction time.
+    rescue OpenSSL::OpenSSLError, ArgumentError
+      raise ConfigurationError, 'Invalid Ed25519 private key', cause: nil
+    end
+
+    def sign(message)
+      Base64.strict_encode64(@key.sign(nil, message))
+    rescue OpenSSL::OpenSSLError
+      raise SignatureError, 'Ed25519 signing failed', cause: nil
+    end
+
+    def self.canonical(method, path, date, nonce, digest = nil)
+      lines = [method.upcase, path, "X-Date:#{date}", "X-Nonce:#{nonce}"]
+      lines << "Digest:#{digest}" if digest
+      lines.join("\n")
+    end
+
+    def self.digest(body)
+      "SHA-256=#{Base64.strict_encode64(Digest::SHA256.digest(body))}"
+    end
+
+    def inspect
+      '#<Lunixi::Signer [REDACTED]>'
+    end
+  end
+end

data/lib/lunixi/transport.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'openssl'
+
+module Lunixi
+  Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+  # Net::HTTP never follows redirects. Each call gets a separate connection,
+  # avoiding sharing mutable Net::HTTP state between application threads.
+  class NetHttpTransport
+    MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+
+    def initialize(timeout: 30, ca_file: nil)
+      @timeout = timeout
+      @ca_file = ca_file
+    end
+
+    def call(method:, uri:, headers:, body:)
+      http = Net::HTTP.new(uri.host, uri.port, nil) # Do not inherit proxy credentials/environment.
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.min_version = OpenSSL::SSL::TLS1_2_VERSION
+      http.ca_file = @ca_file if @ca_file
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+      http.max_retries = 0 # Retry policy belongs to Client, never Net::HTTP.
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, method != 'HEAD', uri.request_uri, headers)
+      request.body = body unless body.nil?
+      data = +''
+      result = nil
+      http.start do |session|
+        session.request(request) do |response|
+          response.read_body do |chunk|
+            data << chunk
+            raise TransportError, 'Gateway response exceeds the size limit' if data.bytesize > MAX_RESPONSE_BYTES
+          end
+          result = Response.new(status: response.code.to_i, headers: response.each_header.to_h, body: data)
+        end
+      end
+      result
+    rescue Timeout::Error, IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError
+      raise TransportError, 'Gateway connection failed; reconcile an uncertain payment before retrying', cause: nil
+    end
+  end
+end

data/lib/lunixi/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lunixi
+  VERSION = '0.1.2'
+end

data/lib/lunixi/webhook.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Lunixi
+  VerifiedEvent = Struct.new(:id, :type, :data, :raw, :body_digest, keyword_init: true)
+
+  # Pure verification never consumes an event id. Use #process with a durable
+  # transactional store so a crashed handler can safely receive the event again.
+  class WebhookVerifier
+    def initialize(secret:, previous_secrets: [], tolerance: 300, clock: -> { Time.now.utc })
+      @secrets = [secret, *previous_secrets]
+      unless @secrets.all? { |value| value.is_a?(String) && !value.empty? } && @secrets.size <= 3
+        raise ConfigurationError, 'One webhook secret and at most two previous secrets are required'
+      end
+
+      @secrets = @secrets.map { |value| value.dup.freeze }.freeze
+      raise ConfigurationError, 'Webhook tolerance must be between 1 and 3600 seconds' unless tolerance.is_a?(Integer) && tolerance.between?(1, 3600)
+
+      @tolerance = tolerance
+      @clock = clock
+    end
+
+    def verify(raw_body, headers)
+      unless raw_body.is_a?(String) && raw_body.bytesize <= 1024 * 1024 && raw_body.dup.force_encoding('UTF-8').valid_encoding?
+        raise WebhookError, 'Webhook body must be bounded UTF-8 bytes'
+      end
+
+      raw_body = raw_body.dup.freeze
+      normalized = normalize_headers(headers)
+      id, timestamp, signature = signature_fields(normalized)
+      verify_signature(raw_body, id, timestamp, signature)
+      envelope = JSON.parse(raw_body, max_nesting: 64, object_class: UniqueJsonObject, allow_duplicate_key: false)
+      event_from_envelope(envelope, normalized, id, raw_body)
+    rescue JSON::ParserError, ArgumentError
+      raise WebhookError, 'Webhook data or timestamp is malformed', cause: nil
+    end
+
+    # The store must commit its receipt and all handler changes atomically. Its
+    # process_once(id:, digest:) yields once, returns :processed or :duplicate,
+    # and raises ReplayConflict when the same id has a different body digest.
+    def process(raw_body, headers, store:)
+      event = verify(raw_body, headers)
+      store.process_once(id: event.id, digest: event.body_digest) { yield event }
+    end
+
+    def inspect
+      '#<Lunixi::WebhookVerifier secrets=[REDACTED]>'
+    end
+
+    private
+
+    def signature_fields(headers)
+      id = headers['x-lunixi-event-id']
+      timestamp = headers['x-lunixi-signature-timestamp']
+      signature = headers['x-lunixi-signature']
+      valid_id = id&.match?(/\A[a-zA-Z0-9_.:-]{1,200}\z/)
+      valid_time = timestamp&.match?(/\A\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?(?:Z|[+-]\d\d:\d\d)\z/)
+      raise WebhookError, 'Required webhook headers are missing or malformed' unless valid_id && valid_time && signature && signature.bytesize <= 2048
+      raise WebhookError, 'Webhook timestamp is outside the tolerance window' if (@clock.call - Time.iso8601(timestamp)).abs > @tolerance
+
+      [id, timestamp, signature]
+    end
+
+    def verify_signature(raw_body, id, timestamp, signature)
+      candidates = signature.split(',').filter_map do |item|
+        match = /\Av2=([a-fA-F0-9]{64})\z/.match(item.strip)
+        match && match[1].downcase
+      end
+      raise WebhookError, 'Webhook requires a v2 signature' if candidates.empty? || candidates.size > 8
+
+      signed = "#{id}.#{timestamp}.".b + raw_body.b
+      matches = @secrets.flat_map do |secret|
+        expected = OpenSSL::HMAC.hexdigest('SHA256', secret, signed)
+        candidates.map { |candidate| OpenSSL.fixed_length_secure_compare(expected, candidate) }
+      end
+      raise WebhookError, 'Webhook signature is invalid' unless matches.include?(true)
+    end
+
+    def event_from_envelope(envelope, normalized, id, raw_body)
+      raise WebhookError, 'Webhook envelope must be an object' unless envelope.is_a?(Hash)
+
+      %w[id eventId].each do |field|
+        raise WebhookError, 'Webhook event id does not match the signed header' if envelope.key?(field) && envelope[field] != id
+      end
+      type = event_type(envelope, normalized)
+      data = envelope['data'] || envelope['payload'] || {}
+      raise WebhookError, 'Webhook data must be an object' unless data.is_a?(Hash)
+
+      VerifiedEvent.new(id: id.freeze, type: type.freeze, data: deep_freeze(data),
+                        raw: deep_freeze(envelope), body_digest: Digest::SHA256.hexdigest(raw_body)).freeze
+    end
+
+    def event_type(envelope, normalized)
+      types = %w[type eventType].filter_map { |field| envelope[field] }
+      raise WebhookError, 'Webhook event type must be present in the signed body' if types.empty?
+
+      header_type = normalized['x-lunixi-event-type']
+      types << header_type if header_type
+      unless !types.empty? && types.all? { |type| type.is_a?(String) && type.match?(/\A[a-zA-Z0-9_.:-]{1,200}\z/) } && types.uniq.one?
+        raise WebhookError, 'Webhook event type is missing or inconsistent'
+      end
+
+      types.first
+    end
+
+    def normalize_headers(headers)
+      raise WebhookError, 'Webhook headers must be a hash' unless headers.is_a?(Hash)
+
+      headers.each_with_object({}) do |(name, value), result|
+        key = name.to_s.downcase
+        raise WebhookError, 'Duplicate or invalid webhook header' if result.key?(key) || !value.is_a?(String)
+
+        result[key] = value.dup.freeze
+      end
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each do |key, entry|
+        key.freeze
+        deep_freeze(entry)
+      end
+      when Array then value.each { |entry| deep_freeze(entry) }
+      end
+      value.freeze
+    end
+  end
+
+  # JSON.parse otherwise silently overwrites duplicate keys, which can make two
+  # applications interpret a signed JSON envelope differently.
+  class UniqueJsonObject < Hash
+    def []=(key, value)
+      raise WebhookError, 'Webhook contains duplicate JSON keys' if key?(key)
+
+      super
+    end
+  end
+end

data/lib/lunixi.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'lunixi/version'
+require_relative 'lunixi/errors'
+require_relative 'lunixi/json_body'
+require_relative 'lunixi/signer'
+require_relative 'lunixi/transport'
+require_relative 'lunixi/payments'
+require_relative 'lunixi/checkout'
+require_relative 'lunixi/fraud'
+require_relative 'lunixi/client'
+require_relative 'lunixi/webhook'