openreceive-server 0.4.10 → 0.4.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c474debc4035b3cb2f6a5b4f3b7e4ee3088c99abfead02e92e23a37d4a26b5db
-  data.tar.gz: ba690e555070b4349fff546f99b2fc737f2787607593c6577fb7ef3bdc849007
+  metadata.gz: c33517376bf957f25550f721694be4652218083b8026847ce2836c7dbd586464
+  data.tar.gz: 14988254c0ec4cb7cbccc4a44733c20ef7a3860f870242b0184e1f3a895f4173
 SHA512:
-  metadata.gz: cf6536250d18edf1a741d32cdb30aac45a309b1663c9ae2e219df5897987e7d53f0f6dc522a6309bd73faec98f65bdbb45f4882779ad5e9a1b369da04b04e0c0
-  data.tar.gz: 4526bd34483b0b3d9480cf25d13c291cecc0a7d3bae9155be76fa677e07a17ed99c8d5d0eb27bc3fac010fdf12c9b09c23492cffdc0e0c17f5b1ddc3f37635ed
+  metadata.gz: a95e7527885746968412329f1bcde0a810533dc6c970f4aa7fb620e3fad02087d97c99551771f7c7c08e108044a1501a650f6e234e3da3d073ae3e0a1fe65e76
+  data.tar.gz: 493ae52bcf9179b3af779d50697f8b9fe03e62dfd0277797056ad50f268e80a6a2f5f77f51583e642a4d07b8387c41960a295aa33065165b36c97d65ac74800c

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.4.13 - 2026-10-01
+
+Release in lockstep with the 0.4.13 reconciliation fixes (in
+`openreceive-rails`: a slow wallet no longer livelocks the reconcile pass,
+host-clock attempts get their own scan window, the gate floor is 3 s). No
+change to this gem's API.
+
+## 0.4.12 - 2026-10-01
+
+Release in lockstep with the 0.4.12 checkout fixes. The swap deposit
+warning text the browser shows no longer carries the "pay with one method
+only" sentence; it is built in the browser package, not here. No Ruby server
+API or payment behavior changes.
+
+## 0.4.11 - 2026-09-21
+
+The mounted HTTP routes mint invoices with the host's own description. The
+display string `amount_for` returns beside the price is now the default
+`make_invoice` memo, so a host that writes no invoice code stops minting
+BOLT11s with an empty description. An explicit request-body `memo` still wins
+and still carries the length cap; a host that returns no description still
+mints without one.
+
+Payment safety and disclosure fixes: a checkout's `created_at_source` (whether
+the creation time came from the wallet or from us) is internal and is stripped
+from every public body, error responses carry a redacted message and no
+arbitrary internal `details`, unexpected errors are reported to `Rails.error`
+detached from their cause and backtrace, a host callback that returns an
+invalid amount raises `InternalHostError` instead of leaking a validation
+failure, and a refund address is rejected unless the attempt has a saved,
+supported pay-in asset. A host that refuses an attempt now answers 409 with
+instructions withheld, while genuine storage failure stays a retryable 503.
+
 ## 0.4.10 - 2026-09-16
 
 Release in lockstep with the 0.4.10 stablecoin checkout fix. The swap fee

data/lib/openreceive/server/errors.rb

@@ -97,7 +97,7 @@ module OpenReceive
     class HostPersistenceError < StandardError
       attr_reader :status, :code, :retryable
 
-      def initialize(message = "The host could not persist this payment attempt; " \
+      def initialize(message = "Payment storage is unavailable; " \
                                "payer instructions were withheld. Please retry.")
         super(message)
         @status = 503

data/lib/openreceive/server/request_handler.rb

@@ -88,7 +88,7 @@ module OpenReceive
                      else
                        @service.create_checkout(
                          "reference" => reference, "amount" => required_amount(resolved),
-                         "memo" => validated_memo(body), "metadata" => body["metadata"]
+                         "memo" => mint_memo(body, resolved), "metadata" => body["metadata"]
                        )
                      end
           commit(checkout, nil, request) unless resolved["payment_hash"]
@@ -99,7 +99,7 @@ module OpenReceive
           # committed invoice amount — and served on the re-fetch path too, so
           # a repeated create answers with the same shape it first did.
           payment_methods = @service.list_swap_options(amount_msats: checkout["amount_msats"])
-          body = { "checkout" => checkout, "payment_methods" => payment_methods }
+          body = { "checkout" => public_checkout(checkout), "payment_methods" => payment_methods }
           description = resolved_description(resolved)
           body["description"] = description if description
           success(201, body, request_id)
@@ -180,7 +180,7 @@ module OpenReceive
                      "reference" => reference,
                      "amount" => required_amount(resolved),
                      "pay_in_asset" => asset,
-                     "memo" => validated_memo(body),
+                     "memo" => mint_memo(body, resolved),
                      "metadata" => body["metadata"]
                    )
                  end
@@ -255,9 +255,9 @@ module OpenReceive
           retryable = Nwc::RETRYABLE_ERROR_CODES.include?(code) if retryable.nil?
           status = retryable ? 503 : 502
         end
-        body = { "code" => code, "message" => error.message, "request_id" => request_id }
+        body = { "code" => code, "message" => Nwc.redact_error_text(error.message), "request_id" => request_id }
         body["retryable"] = retryable unless retryable.nil?
-        body["details"] = error.details if error.respond_to?(:details) && error.details.is_a?(Hash)
+        # Arbitrary internal details and causes have no public projection.
         response_headers = headers(request_id)
         # Mirrors the JS handler: a Retry-After hint (whole seconds, minimum 1)
         # rides along with retryable throttling errors.
@@ -271,6 +271,10 @@ module OpenReceive
 
       private
 
+      def public_checkout(checkout)
+        checkout.reject { |key, _| key.to_s == "created_at_source" }
+      end
+
       # Status refresh with no request-level pass: one-attempt reconcile_payments,
       # delivering settlement inline. A truncated walk raises WalletUnavailableError
       # (retryable 503) rather than reporting not_found.
@@ -391,11 +395,11 @@ module OpenReceive
         # (database down, bug): retryable 503, never a payer-blaming conflict
         # — mirrors the JS handler's commit().
         raise e if e.respond_to?(:status) && e.respond_to?(:code)
-        raise HostPersistenceError
+        raise ConflictError, "The host did not accept this payment attempt; payer instructions were withheld."
       end
 
       def public_swap(swap)
-        swap.reject { |key, _| key == "swap_data" }
+        swap.reject { |key, _| key == "swap_data" }.merge("checkout" => public_checkout(swap.fetch("checkout")))
       end
 
       # Payer-facing subset of a settlement's wallet details, whitelisted
@@ -442,7 +446,9 @@ module OpenReceive
       # preimages.
       def report_unexpected_error(error, request_id)
         if defined?(::Rails) && ::Rails.respond_to?(:error) && ::Rails.error
-          ::Rails.error.report(error, handled: true, source: "openreceive")
+          # Detached diagnostic: no cause, stack or attached provider configuration.
+          safe_error = RuntimeError.new(OpenReceive::Nwc.redact_error_text(error.message))
+          ::Rails.error.report(safe_error, handled: true, source: "openreceive")
         else
           origin = Array(error.backtrace).first
           line = "[openreceive] unexpected #{error.class} (request_id=#{request_id})" \
@@ -550,10 +556,24 @@ module OpenReceive
         memo
       end
 
+      # The description that goes INTO the invoice. An explicit body memo wins,
+      # so a client that writes its own copy keeps it; otherwise the host's
+      # display string is it. Without the fallback a host on the mounted routes
+      # mints BOLT11s with no description at all and the payer's wallet shows a
+      # blank line next to the amount. Only the body memo carries the length
+      # cap: the cap bounds client input, and the host description is host data
+      # exactly like the price beside it.
+      def mint_memo(body, resolved)
+        memo = validated_memo(body)
+        blank = memo.nil? || (memo.is_a?(String) && memo.strip.empty?)
+        blank ? resolved_description(resolved) : memo
+      end
+
       # What the payer is buying, in the host's own words: one optional display
-      # string the host returns beside the price. Response only — it is never
-      # read from a request body, because the payer does not get to write the
-      # copy next to the amount. Blank is the same as absent.
+      # string the host returns beside the price. Never read from a request
+      # body, because the payer does not get to write the copy next to the
+      # amount; it rides the prepare and create responses and, via mint_memo,
+      # defaults the invoice description. Blank is the same as absent.
       def resolved_description(resolved)
         value = resolved["description"]
         return nil unless value.is_a?(String)

data/lib/openreceive/server/service.rb

@@ -162,6 +162,7 @@ module OpenReceive
             "bolt11" => wallet.fetch("invoice"),
             "amount_msats" => wallet.fetch("amount_msats"),
             "created_at" => created_at,
+            "created_at_source" => wallet["created_at"].nil? ? "host" : "wallet",
             "expires_at" => expires_at,
             "fiat_quote" => fiat_quote
           }
@@ -563,6 +564,12 @@ module OpenReceive
       end
 
       def resolve_amount(input)
+        resolve_amount_value(input)
+      rescue ArgumentError, TypeError, KeyError, ValidationError
+        raise InternalHostError, "The host supplied an invalid payment amount."
+      end
+
+      def resolve_amount_value(input)
         amount = stringify(input)
         if amount.key?("sats")
           return [OpenReceive::Money.direct_to_msats(currency: "SATS", value: amount.fetch("sats")), nil]
@@ -639,6 +646,9 @@ module OpenReceive
       # checksum — a false accept here sends the payer's money somewhere
       # unrecoverable. Mirrors the JS normalizeRefundAddress exactly.
       def normalize_refund_address(value, pay_in_asset)
+        unless OpenReceive::Server::Swap::Assets::PAY_IN_ASSETS.include?(pay_in_asset)
+          raise InternalHostError, "Swap recovery requires a supported pay-in asset/network."
+        end
         normalized = value.to_s.strip
         if normalized.empty? || normalized.length > 300
           raise ValidationError, "refundAddress is invalid."

data/lib/openreceive/server/swap/fixedfloat.rb

@@ -306,9 +306,7 @@ module OpenReceive
         def post(path, body)
           @weight_budget&.reserve(path)
           body_string = JSON.generate(body)
-          # Surface every outbound request before the call. The host sink is
-          # responsible for sanitizing nested secrets; the API key and HMAC
-          # signature live in headers and are deliberately never logged.
+          # Host diagnostic sinks receive summaries only, before any provider I/O.
           log_api_request(path, body)
           begin
             response = @http.call(
@@ -341,9 +339,7 @@ module OpenReceive
               message: "FixedFloat #{path} returned invalid JSON."
             )
           end
-          # Surface every response (including API-error envelopes) before any
-          # raise. The host sink sanitizes nested secrets — notably the order
-          # token in a create/order response — so this must not pre-redact.
+          # Summarize before invoking any host sink, including error envelopes.
           log_api_response(path: path, status: status, ok: ok,
                            code: parsed["code"], msg: parsed["msg"], data: parsed["data"])
           unless ok
@@ -369,7 +365,10 @@ module OpenReceive
         end
 
         def log_api_request(path, body = {})
-          @api_request_logger&.call("provider" => @name, "path" => path, "body" => body)
+          @api_request_logger&.call(
+            "provider" => @name, "path" => path, "has_body" => !body.empty?,
+            "has_token" => body.is_a?(Hash) && !body["token"].nil?
+          )
         rescue StandardError
           nil
         end
@@ -377,7 +376,7 @@ module OpenReceive
         def log_api_response(path:, status:, ok:, code: nil, msg: nil, data: nil)
           @api_response_logger&.call(
             "provider" => @name, "path" => path, "status" => status, "ok" => ok,
-            "code" => code, "msg" => msg, "data" => data
+            "code" => code.is_a?(Numeric) ? code : nil, "has_data" => !data.nil?
           )
         rescue StandardError
           nil

data/lib/openreceive/server/version.rb

@@ -2,6 +2,6 @@
 
 module OpenReceive
   module Server
-    VERSION = "0.4.10"
+    VERSION = "0.4.13"
   end
 end

data/skills/debug-openreceive-payment/SKILL.md

@@ -49,7 +49,7 @@ same diagnostics redacted, always exit 0 — safe to share.
 ## 4. Paid but never settles
 
 - Settlement is opportunistic: any OpenReceive request runs one reconcile pass
-  through a durable gate (min 2s between wallet scans, stretched by invoice
+  through a durable gate (min 3s between wallet scans, stretched by invoice
   age). A quiet server settles on the next request — or run the optional
   notification worker. No timer is missing; that is the design.
 - An unpaid attempt closes only after a successful wallet scan at/after expiry

data/skills/integrate-openreceive/SKILL.md

@@ -34,9 +34,10 @@ code** (`NWC_URI`).
    - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
      configured in BTCPay's store UI or Greenfield API; no application code,
      no npm packages, no gem. The rest of this file is about the library.
-3. Follow its **Step 0** first: confirm `NWC_URI` is set in the server
-   environment before writing code. Never print the value; never invent a
-   placeholder.
+3. Follow its **Step 0** first: before writing code or searching the machine,
+   ask the user for the receive-only NWC code (then the swap URI), one question
+   per message, and store each pasted code in the project's env file yourself.
+   Never print the value; never invent a placeholder.
 
 Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
 Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:

data/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.13.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
@@ -35,10 +35,12 @@ refund path on the same checkout screen.
 1. Confirm the BTCPay Server version is 2.4.4 or later (Server Settings →
    About, or `GET /api/v1/server/info`). The plugin declares that minimum and
    BTCPay refuses to load it below.
-2. Check whether the plugin is installed (Server Settings → Plugins, or the
-   store navigation shows an "OpenReceive" entry). If not, install it from the
-   BTCPay plugin directory (Server Settings → Plugins, search "OpenReceive"),
-   as the quickstart says; do not invent an installer command.
+2. Check whether the plugin is installed (the Plugins menu — the plug icon in
+   the top-right corner — under Installed Plugins, or the store navigation
+   shows an "OpenReceive" entry). If not, install it from the BTCPay plugin
+   directory (the same Plugins menu → Plugin Directory, search "openreceive",
+   then Install and Restart now), as the quickstart says; do not invent an
+   installer command.
 3. Check whether the store already has an OpenReceive connection:
    `GET /api/v1/stores/{storeId}/openreceive/settings` returns
    `lightningNodeIsOpenReceive`. If true, the wallet step is done — go to
@@ -119,6 +121,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the plugin itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -131,15 +135,15 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-btcp
 Requires BTCPay Server ≥ 2.4.4.
 
 The OpenReceive plugin makes a receive-only NWC wallet the Lightning node of a
-BTCPay store. BTCPay mints every Lightning invoice in that wallet and records
-payments through its own settlement machinery. Optionally, payers can pay a
-BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
-provider; the swap settles into the same wallet. The store's internal node is
+BTCPay store. BTCPay creates every Lightning invoice in that wallet. It records
+payments the same way it records any other payment. You can also let payers pay
+a BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
+provider. The swap pays into the same wallet. The store's internal node is
 never used.
 
 This is not the Node or Rails library. There are no hooks, no
-`openreceive_payments` table and no OpenReceive HTTP routes: BTCPay's
-invoices, checkout, webhooks and Greenfield API are the host.
+`openreceive_payments` table and no OpenReceive HTTP routes. BTCPay's own
+invoices, checkout, webhooks and Greenfield API do that work.
 
 ### 1. Prerequisites
 
@@ -155,39 +159,66 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 ### 2. Install the plugin
 
-In BTCPay, open **Server Settings → Plugins**, search the plugin directory
-for **OpenReceive**, click **Install**, and restart BTCPay when prompted.
-BTCPay creates the plugin's one table (`openreceive_swaps`, schema
-`BTCPayServer.Plugins.OpenReceive`) in its own Postgres at startup; nothing
-else is created.
+Sign in as a **server administrator**. If someone else hosts your server, ask
+them to install the plugin for you.
+
+**1. Open the Plugins menu.** It is the plug icon in the top-right corner.
+
+**2. Click Plugin Directory.**
+
+**3. Search for `openreceive`** and click the **OpenReceive** result.
+
+**4. Click Install in BTCPay Server.** Confirm when prompted, then click
+**Restart now** and wait for BTCPay to come back.
+
+At startup, BTCPay creates the plugin's two tables in its own Postgres
+database: `openreceive_invoices` and `openreceive_swaps`, in the schema
+`BTCPayServer.Plugins.OpenReceive`. Nothing else is created.
 
 To build the plugin from source instead, follow
 [the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).
 
 ### 3. Connect the wallet
 
-Follow the plugin README's illustrated walkthrough:
-[OpenReceive for BTCPay Server](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
-It opens the **OpenReceive** page in the store's sidebar, saves the
-receive-only NWC code, optionally saves the LSC code to turn swaps on, and
-creates a first test invoice. There is nothing else to configure: you never
-open BTCPay's Lightning node screen, and the plugin never reads the internal
-node.
+1. Select your store and open **OpenReceive** in its sidebar, under Wallets.
+2. Paste your receive-only NWC code. To see what the wallet supports first,
+   click **Test connection**.
+3. Click **Save NWC Code**.
+4. To turn swaps on, paste a Lightning Swap Connect code and click **Save swap
+   settings**.
 
-Saving fails closed if the wallet advertises a spend method such as
-`pay_invoice`. Mint a receive-only code instead; the override for a wallet
-that cannot is a deliberate, logged choice. Swaps raise the store's invoice
-expiration to 60 minutes when it is shorter, because a swap needs at least 45
-minutes of invoice life.
+The page then shows **Wallet connected**. If you set up a provider, it also
+shows **Swaps on**. There is nothing else to configure. You never open BTCPay's
+Lightning node screen, and the plugin never reads the internal node.
+
+Screenshots for each of those steps, and for creating a first test invoice,
+are in the plugin's
+[README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
+
+The plugin refuses to save a code whose wallet advertises a spend method such
+as `pay_invoice`. Create a receive-only code instead. If your wallet cannot
+make one, there is an override, but using it is a deliberate choice and the
+plugin logs it.
+
+Turning swaps on raises the store's invoice expiration to 60 minutes if it is
+shorter. A swap needs the invoice to stay open for at least 45 minutes.
 
 ### 4. Check it
 
-**Run a health check** on the OpenReceive page runs every probe in place:
-the connection, the wallet preflight, payment notifications, the last wallet
-scan, the swap provider and its assets, the invoice expiration, and swaps
-that need a human. Each failing probe carries a fix link.
+Click **Run a health check** on the OpenReceive page. It runs every check
+right there:
+
+- the connection
+- the wallet preflight
+- payment notifications
+- the last wallet scan
+- the swap provider and its assets
+- the invoice expiration
+- swaps that need a human
+
+Each failing check comes with a link to the fix.
 
-Every setting, Greenfield route, swap state, log event and probe is in the
-[BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md), including what is
-unsupported by design: every send-side feature, top-up invoices, and a bare
-`nostr+walletconnect://` string in BTCPay's Lightning node screen.
+The [BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md) lists every setting,
+Greenfield route, swap state, log event and check. It also lists what the
+plugin does not support by design: every send-side feature, top-up invoices,
+and a bare `nostr+walletconnect://` string in BTCPay's Lightning node screen.