lipwa 0.1.2 → 0.1.3

data/docs/capabilities.md

@@ -0,0 +1,116 @@
+---
+title: Capabilities
+description: Reference for Lipwa payment operations.
+---
+
+<header class="page-title"><p class="eyebrow">Guide 02</p><h1>Capabilities</h1><p class="lead">A capability describes a payment flow. Gateways include only the modules they support.</p></header>
+
+{% highlight ruby %}gateway = Lipwa.gateway(:jenga)
+gateway.capability?(:bank_transfer) # => true{% endhighlight %}
+
+| Capability | Methods | Gateways |
+| --- | --- | --- |
+| `stk_push` | `stk_push` | M-Pesa |
+| `c2b` | `register_urls`, `simulate` | M-Pesa |
+| `disbursement` | `disburse` | M-Pesa, Jenga |
+| `status_query` | `status` | M-Pesa |
+| `refund` | `refund` | M-Pesa |
+| `bank_transfer` | `transfer`, `balance`, `statement` | Co-op, Jenga |
+| `lightning_invoice` | `create_invoice`, `check_invoice` | LNbits-backed gateways |
+| `lightning_payment` | `pay_invoice`, `check_payment` | LNbits-backed gateways |
+
+Lightning invoice amounts are positive integer satoshis (`amount_sats`), not
+`Lipwa::Money` values. A created invoice's BOLT11 string is stored in
+`response.raw["payment_request"]`; its payment hash is
+`response.provider_reference`. Checking an unpaid invoice still returns
+`Success(Response)`, with `response.success? == false`.
+
+Outbound Lightning payments use the separate `lightning_payment` capability
+and require an explicitly configured wallet admin key. That key can spend the
+wallet balance; it never replaces the receive-only invoice key. A payment may
+remain `pending`, and a transport timeout leaves its outcome unknown. Inspect
+`response.raw["status"]` and call `check_payment` to reconcile it; never retry
+an indeterminate payment automatically.
+
+{% highlight ruby %}lnbits.pay_invoice(bolt11: "lnbc...")
+lnbits.check_payment(payment_hash: "..."){% endhighlight %}
+
+
+## Collection
+
+{% highlight ruby %}mpesa = Lipwa.gateway(:mpesa)
+
+mpesa.stk_push(
+  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
+  phone_number: "254712345678",
+  account_reference: "ORDER-123",
+  callback_url: "https://example.com/webhooks/mpesa"
+)
+
+mpesa.register_urls(
+  validation_url: "https://example.com/mpesa/validation",
+  confirmation_url: "https://example.com/mpesa/confirmation"
+)
+
+mpesa.simulate(
+  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
+  phone_number: "254712345678",
+  bill_ref_number: "ORDER-123"
+){% endhighlight %}
+
+`simulate` is for M-Pesa sandbox testing.
+
+## Disbursement, status, and refund
+
+{% highlight ruby %}mpesa.disburse(
+  command_id: "BusinessPayment",
+  amount: Lipwa::Money.new(amount: 500, currency: "KES"),
+  party_b: "254712345678",
+  remarks: "Supplier payout",
+  result_url: "https://example.com/mpesa/payout/result",
+  queue_timeout_url: "https://example.com/mpesa/payout/timeout"
+)
+
+mpesa.status(
+  transaction_id: "OEI2AK4Q16",
+  remarks: "Reconcile order",
+  result_url: "https://example.com/mpesa/status/result",
+  queue_timeout_url: "https://example.com/mpesa/status/timeout"
+)
+
+mpesa.refund(
+  transaction_id: "OEI2AK4Q16",
+  amount: Lipwa::Money.new(amount: 100, currency: "KES"),
+  remarks: "Customer refund",
+  result_url: "https://example.com/mpesa/refund/result",
+  queue_timeout_url: "https://example.com/mpesa/refund/timeout"
+){% endhighlight %}
+
+M-Pesa B2C command IDs are `SalaryPayment`, `BusinessPayment`, and
+`PromotionPayment`. B2B supports `BusinessPayBill`, `BusinessBuyGoods`, and
+`MerchantToMerchantTransfer` and requires `account_reference`.
+
+## Bank operations
+
+{% highlight ruby %}bank = Lipwa.gateway(:jenga)
+
+bank.transfer(
+  rail: :pesalink,
+  amount: Lipwa::Money.new(amount: "2500.00", currency: "KES"),
+  source_account: "00123456789",
+  destination_account: "00987654321",
+  destination_name: "Amina N.",
+  reference: "INV-1042"
+)
+
+bank.balance(account_number: "00123456789")
+bank.statement(account_number: "00123456789",
+               from_date: Date.new(2026, 8, 1),
+               to_date: Date.new(2026, 8, 31)){% endhighlight %}
+
+Rails are `internal`, `rtgs`, `pesalink`, `swift`, and `bill_payment`,
+subject to provider availability. RTGS/SWIFT require
+`destination_bank_code`; bill payment requires `biller_code`. Jenga also
+exposes `forex_rates`.
+
+<nav class="doc-nav"><a href="{{ '/getting-started/' | relative_url }}">← Getting started</a><a href="{{ '/gateways/' | relative_url }}">Gateways →</a></nav>

data/docs/gateways.md

@@ -0,0 +1,158 @@
+---
+title: Gateways
+description: Configure M-Pesa, Co-op Bank, and Jenga HQ.
+---
+
+<header class="page-title"><p class="eyebrow">Guide 03</p><h1>Gateways</h1><p class="lead">Configure process-wide defaults or isolate each tenant's credentials and HTTP settings in a context.</p></header>
+
+## Process-wide defaults
+
+`Lipwa.configure` sets shared `logger`, `default_timeout`, and Faraday `adapter`
+defaults. Gateway-class `.configure` sets provider credentials, environment, and
+HTTP overrides, as shown below. These APIs and `Lipwa.gateway(:mpesa)` remain
+supported and backward compatible; existing single-tenant applications do not
+need to adopt contexts.
+
+Configure defaults at boot before resolving gateways or constructing contexts.
+`Lipwa.gateway(:mpesa)` lazily constructs and memoizes one process-wide gateway.
+Its provider and shared settings are captured on the first lookup; later
+configuration changes do not update that instance. Direct construction with
+`Lipwa::Gateways::Mpesa.new` captures defaults at construction time instead.
+
+## M-Pesa
+
+{% highlight ruby %}Lipwa::Gateways::Mpesa.configure do |c|
+  c.env = :sandbox
+  c.consumer_key = ENV.fetch("MPESA_CONSUMER_KEY")
+  c.consumer_secret = ENV.fetch("MPESA_CONSUMER_SECRET")
+  c.shortcode = ENV.fetch("MPESA_SHORTCODE")
+  c.passkey = ENV.fetch("MPESA_PASSKEY")
+end{% endhighlight %}
+
+Lipwa chooses the Daraja host and manages OAuth tokens.
+
+## Co-op Bank
+
+{% highlight ruby %}Lipwa::Gateways::CoopBank.configure do |c|
+  c.env = :sandbox
+  c.api_key = ENV.fetch("COOP_API_KEY")
+  c.api_secret = ENV.fetch("COOP_API_SECRET")
+  c.base_url = ENV["COOP_BASE_URL"]   # optional override
+  c.token_url = ENV["COOP_TOKEN_URL"] # optional override
+end{% endhighlight %}
+
+`client_id` and `client_secret` are aliases for `api_key` and `api_secret`.
+
+## Jenga HQ
+
+{% highlight ruby %}Lipwa::Gateways::Jenga.configure do |c|
+  c.env = :sandbox
+  c.api_key = ENV.fetch("JENGA_API_KEY")
+  c.merchant_code = ENV.fetch("JENGA_MERCHANT_CODE")
+  c.consumer_secret = ENV.fetch("JENGA_CONSUMER_SECRET")
+  c.private_key = File.read(ENV.fetch("JENGA_PRIVATE_KEY_PATH"))
+  c.source_account = ENV.fetch("JENGA_SOURCE_ACCOUNT")
+  c.source_name = ENV.fetch("JENGA_SOURCE_NAME")
+  c.country_code = "KE"
+  c.partner_id = ENV["JENGA_PARTNER_ID"]
+end{% endhighlight %}
+
+Lipwa obtains bearer tokens and signs provider requests.
+
+## Per-gateway HTTP settings
+
+{% highlight ruby %}Lipwa::Gateways::Jenga.configure do |c|
+  c.timeout = 20
+  c.open_timeout = 5
+  c.logger = MyStructuredLogger.new
+end{% endhighlight %}
+
+Logs recursively redact authorization, credentials, cookies, passwords,
+tokens, and secret-like fields.
+
+## Contexts
+
+`Lipwa.context { |config| ... }` (or `Lipwa::Context.new` with the same block)
+captures `Lipwa.config` and every currently registered gateway class's settings
+before running the builder block. Unspecified settings inherit those captured
+defaults. `config.gateway(:mpesa) { |mpesa| ... }` overrides only that context's
+M-Pesa settings. Provider `timeout` and `logger` take precedence over shared
+`default_timeout` and `logger`; otherwise the shared defaults apply.
+
+The snapshot happens when the context is constructed, even if its first gateway
+lookup is much later. Subsequent global changes and registrations do not alter
+an existing context. Overrides do not change process-wide defaults or other
+contexts. Typed overrides are validated during construction.
+
+When the block finishes, configuration is immutable: configuration strings,
+arrays, and hashes are copied and frozen. Logger and other service objects retain
+their identity rather than being deeply copied or frozen. Gateway runtime state,
+such as HTTP clients and OAuth token caches, can still change.
+
+Each context lazily constructs and memoizes its own gateway instances. Repeated
+`tenant_context.gateway(:mpesa)` calls return the same instance, distinct from
+another context's gateway and from `Lipwa.gateway(:mpesa)`. Built-in provider HTTP
+clients, authentication, and token caches belong to those gateway instances.
+Pass contexts explicitly; there is no thread-local current tenant.
+
+### Retain one context per tenant
+
+Construct one service object per tenant and retain it across payment calls. Here
+`secrets_for` is an application-supplied callable that loads that tenant's secrets
+from your credential store during context construction:
+
+{% highlight ruby %}class TenantPayments
+  attr_reader :context
+
+  def initialize(tenant_id:, secrets_for:)
+    @context = Lipwa.context do |config|
+      secrets = secrets_for.call(tenant_id)
+      config.default_timeout = 20
+      config.gateway(:mpesa) do |mpesa|
+        mpesa.env = :production
+        mpesa.consumer_key = secrets.fetch(:consumer_key)
+        mpesa.consumer_secret = secrets.fetch(:consumer_secret)
+        mpesa.shortcode = secrets.fetch(:shortcode)
+        mpesa.passkey = secrets.fetch(:passkey)
+      end
+    end
+  end
+
+  def stk_push(**params)
+    context.gateway(:mpesa).stk_push(**params)
+  end
+end
+
+# Retain these services in your application's tenant service registry.
+payments_by_tenant = tenant_ids.to_h do |tenant_id|
+  [tenant_id, TenantPayments.new(tenant_id: tenant_id, secrets_for: secrets_for)]
+end
+
+tenant_context = payments_by_tenant.fetch(tenant_id).context
+tenant_context.gateway(:mpesa) # This tenant's memoized gateway
+Lipwa.gateway(:mpesa)          # Separate process-wide gateway using boot defaults
+{% endhighlight %}
+
+Do not repeatedly mutate `Lipwa::Gateways::Mpesa.configure` per request to switch
+tenants: those defaults are shared across requests, and memoized gateways retain
+their earlier snapshots. For credential rotation, construct a replacement service
+and context with fresh secrets and use it for subsequent calls. Existing contexts
+continue using their captured credentials.
+
+Tenant secrets loaded during construction remain covered by Lipwa's HTTP log
+redaction for authorization, credentials, tokens, and secret-like fields. This
+does not sanitize arbitrary application logs: do not log raw secret hashes or
+inspect configuration objects containing credentials.
+
+### Explicit gateway construction and custom authentication
+
+Explicit `config:` and `global_config:` gateway constructor snapshots replace
+their respective defaults and are copied and finalized by the gateway.
+
+Custom `auth_strategy` objects are duplicated for each gateway. Stateful custom
+strategies should implement `initialize_copy` to isolate nested mutable state,
+or supply a zero-argument factory that creates a fresh strategy and token source.
+Callable token providers and clocks must not close over shared mutable token
+caches. Built-in OAuth clients reset their caches when copied.
+
+<nav class="doc-nav"><a href="{{ '/capabilities/' | relative_url }}">← Capabilities</a><a href="{{ '/webhooks/' | relative_url }}">Webhooks →</a></nav>

data/docs/getting-started.md

@@ -0,0 +1,64 @@
+---
+title: Getting started
+description: Install Lipwa, configure a gateway, and make your first request.
+---
+
+<header class="page-title"><p class="eyebrow">Guide 01</p><h1>Getting started</h1><p class="lead">Install the gem, configure one gateway, and handle the result explicitly.</p></header>
+
+## Install and configure
+
+{% highlight bash %}bundle add lipwa{% endhighlight %}
+
+{% highlight ruby %}require "lipwa"
+
+Lipwa.configure do |config|
+  config.logger = Rails.logger
+  config.default_timeout = 10
+end
+
+Lipwa::Gateways::Mpesa.configure do |config|
+  config.env = :sandbox
+  config.consumer_key = ENV.fetch("MPESA_CONSUMER_KEY")
+  config.consumer_secret = ENV.fetch("MPESA_CONSUMER_SECRET")
+  config.shortcode = ENV.fetch("MPESA_SHORTCODE")
+  config.passkey = ENV.fetch("MPESA_PASSKEY")
+end{% endhighlight %}
+
+## Make a request
+
+{% highlight ruby %}result = Lipwa.gateway(:mpesa).stk_push(
+  amount: Lipwa::Money.new(amount: "100.00", currency: "KES"),
+  phone_number: "254712345678",
+  account_reference: "ORDER-123",
+  callback_url: "https://payments.example.com/webhooks/mpesa",
+  idempotency_key: "stk-order-123"
+)
+
+result.either(
+  ->(response) { Payment.update!(provider_reference: response.provider_reference) },
+  ->(error) { logger.error(error.message) }
+){% endhighlight %}
+
+<div class="callout"><strong>Acceptance is not settlement.</strong> STK Push, disbursement, refund, and status calls are asynchronous. Process the later verified callback for the final result.</div>
+
+## Initiator credentials
+
+Disbursement, status, and refund also require:
+
+{% highlight ruby %}Lipwa::Gateways::Mpesa.configure do |config|
+  config.initiator_name = ENV.fetch("MPESA_INITIATOR_NAME")
+  config.initiator_password = ENV.fetch("MPESA_INITIATOR_PASSWORD")
+  config.security_credential_cert =
+    File.read(ENV.fetch("MPESA_CERTIFICATE_PATH"))
+end{% endhighlight %}
+
+Sandbox and production certificates differ. Keep certificate content outside
+source control.
+
+## Idempotency
+
+Reuse one stable `idempotency_key` when retrying one logical write. Lipwa
+retries safe reads automatically, but writes only when this key is present.
+The provider controls key retention and duplicate detection.
+
+<nav class="doc-nav"><a href="{{ '/' | relative_url }}">← Home</a><a href="{{ '/capabilities/' | relative_url }}">Capabilities →</a></nav>

data/docs/index.md

@@ -0,0 +1,46 @@
+---
+title: Home
+description: Unified, capability-based African payment APIs for Ruby.
+---
+
+<section class="hero"><div>
+<p class="eyebrow">Payment flows, honestly modeled</p>
+<h1>One Ruby API. Only the capabilities you need.</h1>
+<p class="lead">Lipwa unifies mobile money, bank transfers, payouts, and asynchronous callbacks without pretending every provider behaves like a card gateway.</p>
+<div class="actions"><a class="button" href="{{ '/getting-started/' | relative_url }}">Get started</a><a class="button secondary" href="{{ '/capabilities/' | relative_url }}">Explore capabilities</a></div>
+</div><div class="terminal"><div class="terminal-bar"><span class="terminal-dot"></span><span class="terminal-dot"></span><span class="terminal-dot"></span></div>
+{% highlight ruby %}gateway = Lipwa.gateway(:mpesa)
+
+result = gateway.stk_push(
+  amount: Lipwa::Money.new(
+    amount: "100.00",
+    currency: "KES"
+  ),
+  phone_number: "254712345678",
+  account_reference: "ORDER-123",
+  callback_url: callback_url,
+  idempotency_key: "stk-order-123"
+)
+
+result.fmap(&:provider_reference){% endhighlight %}
+</div></section>
+
+## Designed around real payment flows
+
+<div class="grid">
+<article class="card"><span class="number">01</span><h3>Capability first</h3><p>Gateways expose operations they truly implement. Inspect support with <code>capability?</code> and route deliberately.</p></article>
+<article class="card"><span class="number">02</span><h3>Failure explicit</h3><p>Validation and provider failures travel through <code>Dry::Monads::Result</code>.</p></article>
+<article class="card"><span class="number">03</span><h3>Async aware</h3><p>Request acknowledgement and final outcome stay distinct. Normalized webhook events complete the flow.</p></article>
+</div>
+
+## Supported gateways
+
+| Gateway | What it can do |
+| --- | --- |
+| M-Pesa | STK Push, C2B, B2C/B2B, status, refunds |
+| Co-op Bank | Transfers, balances, and statements |
+| Jenga HQ | Bank/mobile transfers, account queries, forex |
+
+<div class="callout"><strong>Start with a flow, not a provider.</strong> Choose the capability your product needs, then select a gateway that advertises it.</div>
+
+<nav class="doc-nav"><span></span><a href="{{ '/getting-started/' | relative_url }}">Getting started →</a></nav>

data/docs/reliability.md

@@ -0,0 +1,50 @@
+---
+title: Reliability
+description: Results, retries, idempotency, and money safety.
+---
+
+<header class="page-title"><p class="eyebrow">Guide 05</p><h1>Reliability</h1><p class="lead">Expected failures are explicit, and automatic recovery is limited to operations safe to repeat.</p></header>
+
+## Results and errors
+
+| Type | Delivery | Meaning |
+| --- | --- | --- |
+| `ValidationError` | `Failure` | Input failed a capability contract |
+| `GatewayError` | `Failure` | Network or provider HTTP failure |
+| `WebhookParseError` | `Failure` | Invalid inbound JSON |
+| `ConfigurationError` | raised | Missing or invalid setup |
+| `UnsupportedProviderError` | raised | No webhook parser registered |
+
+`Lipwa::Response` exposes `success?`, `provider_reference`, `message`,
+`code`, and `raw`.
+
+## Retry policy
+
+Lipwa retries transient network exceptions and HTTP 429, 500, 502, 503, and
+504 at most twice. Backoff begins at 0.5 seconds, doubles with up to 50%
+jitter, and caps waits at 5 seconds. Server `Retry-After` and
+`RateLimit-Reset` values are honored within that cap.
+
+Safe reads retry automatically. Writes retry only with `Idempotency-Key`.
+
+## Decimal money
+
+{% highlight ruby %}subtotal = Lipwa::Money.new(amount: "199.95", currency: "KES")
+fee = Lipwa::Money.new(amount: "5.05", currency: "KES")
+
+total = subtotal + fee
+total.to_s       # => "205.0 KES"
+total > subtotal # => true{% endhighlight %}
+
+Amounts and results are non-negative. Addition, subtraction, and comparison
+across currencies raise `ArgumentError`. Currency conversion is never hidden.
+
+## Async reconciliation
+
+1. Persist a pending operation and idempotency key before calling the API.
+2. Store the synchronous provider reference.
+3. Verify and process callbacks idempotently.
+4. Use status query where supported to reconcile missing callbacks.
+5. Treat acknowledgements and callbacks as repeatable messages.
+
+<nav class="doc-nav"><a href="{{ '/webhooks/' | relative_url }}">← Webhooks</a><a href="{{ '/' | relative_url }}">Home →</a></nav>

data/docs/webhooks.md

@@ -0,0 +1,72 @@
+---
+title: Webhooks
+description: Parse and verify M-Pesa, Jenga, and LNbits callbacks.
+---
+
+<header class="page-title"><p class="eyebrow">Guide 04</p><h1>Webhooks</h1><p class="lead">Normalize provider payloads, then perform the provider-specific trust check before changing financial state.</p></header>
+
+## Parse
+
+{% highlight ruby %}result = Lipwa::Webhook.parse_webhook(
+  provider: :mpesa,
+  body: request.body.read,
+  headers: request.headers.to_h
+)
+
+result.either(
+  ->(event) { process_event(event) },
+  ->(error) { head :bad_request }
+){% endhighlight %}
+
+`WebhookEvent` exposes `provider`, `event_type`, `success?`,
+`provider_reference`, `message`, `raw`, and `verify_signature`.
+
+## Verify M-Pesa
+
+Daraja does not cryptographically sign callbacks. Lipwa checks the remote
+address against Safaricom's published callback IP list:
+
+{% highlight ruby %}return head :forbidden unless event.verify_signature(
+  source_ip: request.remote_ip
+){% endhighlight %}
+
+Configure trusted proxies carefully so clients cannot spoof forwarded IPs.
+Event types are `stk_callback`, `c2b`, `transaction_status`,
+`disbursement`, and `refund`.
+
+## Verify Jenga
+
+Jenga receive-payment IPNs normalize to `receive_payment`:
+
+{% highlight ruby %}return head :forbidden unless event.verify_signature(
+  username: ENV.fetch("JENGA_WEBHOOK_USERNAME"),
+  password: ENV.fetch("JENGA_WEBHOOK_PASSWORD")
+){% endhighlight %}
+
+## Verify LNbits
+
+LNbits does not HMAC-sign webhooks by default. Give each invoice a strong,
+random token in its webhook URL, persist that token alongside the payment hash,
+and compare the URL parameter when the callback arrives:
+
+{% highlight ruby %}return head :forbidden unless event.verify_signature(
+  expected_token: invoice.webhook_token,
+  provided_token: params[:token]
+){% endhighlight %}
+
+This is a shared-secret URL check, not proof that the webhook body came from
+LNbits. Anyone who learns the token can forge a payload. Always call
+`check_invoice(payment_hash: event.provider_reference)` and confirm its status
+before crediting funds; use the webhook only as a low-latency trigger.
+
+## Processing checklist
+
+1. Retain the raw body and parse it through Lipwa.
+2. Verify using provider-specific options.
+3. Correlate by `provider_reference`.
+4. Apply the transition idempotently inside a transaction.
+5. Return quickly and defer slow work to a job.
+
+<div class="callout"><strong>Never credit from an unverified callback.</strong> Parsing normalizes data; verification determines trust.</div>
+
+<nav class="doc-nav"><a href="{{ '/gateways/' | relative_url }}">← Gateways</a><a href="{{ '/reliability/' | relative_url }}">Reliability →</a></nav>

data/lib/lipwa/auth_strategies/api_key.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Lipwa
+  module AuthStrategies
+    # Sets a static API key header on every request.
+    class ApiKey < Base
+      def initialize(key, header: "X-Api-Key")
+        raise ArgumentError, "key must not be blank" if key.nil? || key.to_s.strip.empty?
+
+        super()
+        @key = key
+        @header = header
+      end
+
+      def initialize_copy(source)
+        super
+        @key = @key.dup
+        @header = @header.dup
+      end
+
+      def apply(env)
+        env.request_headers[@header] = @key
+      end
+    end
+  end
+end

data/lib/lipwa/auth_strategies/base.rb

@@ -8,6 +8,10 @@ module Lipwa
     # timestamp, whatever the provider needs) without HttpAdapter knowing
     # which kind of auth it's dealing with.
     class Base
+      def inspect
+        "#<#{self.class}:0x#{object_id.to_s(16)}>"
+      end
+
       # env is a Faraday::Env — mutate env.request_headers / env.body
       # in place. Must be implemented by subclasses.
       def apply(env)

data/lib/lipwa/auth_strategies/bearer_token.rb

@@ -19,6 +19,11 @@ module Lipwa
         @token_provider = token_provider
       end
 
+      def initialize_copy(source)
+        super
+        @token_provider = @token_provider.dup
+      end
+
       def apply(env)
         env.request_headers["Authorization"] = "Bearer #{@token_provider.call}"
       end

data/lib/lipwa/auth_strategies/jenga.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require_relative "base"
+
+module Lipwa
+  module AuthStrategies
+    # Adds Jenga HQ's OAuth2 bearer token and RSA-SHA256 request signature.
+    #
+    # Jenga defines a different signature formula for each endpoint. The
+    # signature_payload callable receives the Faraday::Env for the outgoing
+    # request and must return the exact concatenated String required by that
+    # endpoint (without separators). It is evaluated for every request.
+    class Jenga < Base
+      def initialize(token_provider:, private_key:, signature_payload:)
+        super()
+        validate_callable!(token_provider, :token_provider)
+        validate_callable!(signature_payload, :signature_payload)
+
+        @token_provider = token_provider
+        @private_key = parse_private_key(private_key)
+        @signature_payload = signature_payload
+      end
+
+      def initialize_copy(source)
+        super
+        @token_provider = @token_provider.dup
+      end
+
+      def apply(env)
+        payload = @signature_payload.call(env)
+        raise ArgumentError, "signature_payload must return a String" unless payload.is_a?(String)
+
+        signature = @private_key.sign(OpenSSL::Digest.new("SHA256"), payload)
+        env.request_headers["Authorization"] = "Bearer #{@token_provider.call}"
+        env.request_headers["Signature"] = Base64.strict_encode64(signature)
+      end
+
+      private
+
+      def validate_callable!(value, name)
+        raise ArgumentError, "#{name} must respond to #call" unless value.respond_to?(:call)
+      end
+
+      def parse_private_key(private_key)
+        key = private_key.is_a?(OpenSSL::PKey::RSA) ? private_key : OpenSSL::PKey::RSA.new(private_key)
+        raise ArgumentError, "private_key must contain an RSA private key" unless key.private?
+
+        key
+      rescue OpenSSL::PKey::PKeyError, TypeError
+        raise ArgumentError, "private_key must be an RSA private key or PEM encoded RSA private key"
+      end
+    end
+
+    JengaHQ = Jenga
+  end
+end

data/lib/lipwa/auth_strategies.rb

@@ -3,3 +3,5 @@
 require_relative "auth_strategies/base"
 require_relative "auth_strategies/none"
 require_relative "auth_strategies/bearer_token"
+require_relative "auth_strategies/api_key"
+require_relative "auth_strategies/jenga"

data/lib/lipwa/capabilities/authorize.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require_relative "../capability"
+require_relative "../contracts/card_payment_contract"
+
+module Lipwa
+  module Capabilities
+    # Creates a provider authorization flow without exposing card data.
+    module Authorize
+      extend Lipwa::Capability
+      include Dry::Monads[:result]
+      self.capability_name = :authorize
+
+      CONTRACT = Lipwa::Contracts::CardPaymentContract.new
+
+      def authorize(**params)
+        idempotency_key = params.delete(:idempotency_key)
+        validation = CONTRACT.call(params)
+        return Failure(Lipwa::ValidationError.new(validation)) if validation.failure?
+
+        perform_authorize(validation.to_h, idempotency_key)
+      end
+    end
+  end
+end