openreceive-rails 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fd30ded365e254b6529fc4c006d8ec597a83f659cdf4b60b34127817d7fc995
-  data.tar.gz: b272234e0a5eadb74ac2c63a9df71d3af0cc62d290497005af206653a489743d
+  metadata.gz: 0b3e0d9d08672c321e8e58648f9b59b3ffe28f373a6cf53c832d25dbeeb5cd32
+  data.tar.gz: 5f5919293c2fa6ded10cbaa28e6fd6406cb84d7348e180c0d8fc62dd762c9473
 SHA512:
-  metadata.gz: 85bdd9b23bc16d13d4e1b3e4d7bc788cf2987c44431a9c345c9a6f48c63aea11f27e8c8ab7d40b1343e787048a15768eed8baaf40bf60d2e6b6b27fedb1d5d47
-  data.tar.gz: 8ed6a9cd303864c971b5b8597e34cbe2e1e6b2cf9e5b1651a38f6183e43f4f69ab1a05af90c364f237b3698432c101c059eaf61bba9738cae692a4aea65ffb93
+  metadata.gz: 19f46e2352fcb7362a53b5ace86f263800b729b8c044e388ffde0c8636cac2d1f2dc9bf88879501da93a7c254bd03843e7742e68b5524e3115ab57016ffe1359
+  data.tar.gz: 5786094d5d457e28251ff6cac9467b7561d4ab466a83df93ab3d0086e5c6bd2ac29f2328ae6bd1ee259878f5fd2085e164a7685436a6b3905aaae574084dcae2

data/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.3.1 - 2026-08-28
+
+### The generated allow-all `config.authorize` is no longer silent
+
+`openreceive:install` writes a `config.authorize` that allows every request,
+treating possession of the reference as the authorization. It is now the named
+constant `OpenReceive::ALLOW_ALL_AUTHORIZE`, for the same reason
+`LOGGING_ON_PAID` is a constant: the engine detects it at boot by identity and
+warns that anyone holding an order id can mint invoices, poll status and request
+refunds for it. Safe only while references are unguessable. The five-minute demo
+still works; it just stops being quiet about what it is.
+
+### `bin/rails openreceive:doctor`
+
+Step 0 of the agent directions as one command. It reports credential PRESENCE
+only — every line is `set` or `unset`, and no secret is printed, echoed or
+partially shown, which is what makes it safe to run in a shared terminal or
+paste into an issue. Alongside that: whether `OpenReceive.configure` ran, which
+hooks are missing or still the generated placeholders, where the engine is
+mounted, and a wallet preflight.
+
+The wallet line is last and best-effort. It builds the service — the same eager
+preflight production boot runs, so a missing `NWC_URI`, a dead relay or a
+SPEND-CAPABLE connection all answer here rather than on a payer's first checkout
+— and reports the failure sanitized rather than raising it, because a doctor
+that dies at line six tells an operator less than one that finishes.
+
+"Look for `NWC_URI` in this app's server environment" has a different answer on
+every host shape, and in a containerised app grepping the repo finds the name in
+a compose file and proves nothing about the value. This asks the process, which
+is the only place that always knows.
+
+## 0.3.0 - 2026-08-26
+
+### `config.amount_for` may return a `:description` beside the price
+
+One optional display string — what the payer is buying — returned from the same
+hook that already answers the price:
+
+```ruby
+config.amount_for = lambda do |reference|
+  order = Order.find_by(reference: reference)
+  next nil unless order
+  { currency: "USD", value: order.total.to_s, description: "#{order.line_items.size} items" }
+end
+```
+
+The engine peels it off before the amount reaches the minting service, and the
+handler echoes it on the prepare and create responses, where both shipped
+checkout renderers draw it above the amount. Deliberately one string and not a
+line-item schema: OpenReceive owns no orders. The install generator's
+initializer documents it inline.
+
+The full release narrative lives in the repository-root
+[CHANGELOG](https://github.com/openreceive/openreceive/blob/master/CHANGELOG.md).
+
+## 0.2.4 - 2026-08-26
+
+No Ruby changes in this release. 0.2.4 is browser-side only —
+`@openreceive/browser`, `@openreceive/elements`, `@openreceive/react` and
+`@openreceive/provider-data`. This gem is byte-identical to 0.2.3 and ships to
+keep the one-version-for-everything rule, so the engine, the HTTP contract and
+the settlement path are unchanged. The full release narrative lives in the
+repository-root
+[CHANGELOG](https://github.com/openreceive/openreceive/blob/master/CHANGELOG.md).
+
 ## 0.2.3 - 2026-08-25
 
 The Ruby gems release in lockstep with the npm workspace version. The full

data/lib/generators/openreceive/install/templates/initializer.rb

@@ -21,8 +21,9 @@ OpenReceive.configure do |config|
   #                        prove this caller owns it.
   # Return true to allow the request, false for a 403.
   #
-  # The default below allows every request, treating possession of the
-  # reference as the authorization (an unknown reference is still a 404,
+  # The default below is a NAMED PLACEHOLDER, and the engine warns at boot for
+  # as long as it is still here. It allows every request, treating possession of
+  # the reference as the authorization (an unknown reference is still a 404,
   # because amount_for returns nil for it). That is only safe while your
   # references are unguessable (UUIDs, not sequential integers). If they are
   # enumerable, or an order should only be visible to the customer who placed
@@ -32,7 +33,7 @@ OpenReceive.configure do |config|
   #     order = Order.find_by(id: context[:resource][:reference])
   #     order && order.user_id == context[:request].session[:user_id]
   #   end
-  config.authorize = ->(_context) { true }
+  config.authorize = OpenReceive::ALLOW_ALL_AUTHORIZE
 
   # The price for a reference — the string your checkout passes, typically
   # your order id. Your application is the only price authority; payer input
@@ -40,10 +41,17 @@ OpenReceive.configure do |config|
   # { sats: 1200 }, or nil when there is nothing to pay for (a 404). The
   # engine refuses to serve checkouts until this is set.
   #
+  # An optional :description beside the price is what the payer is BUYING, in
+  # your own words — one display string the checkout renders above the amount.
+  # Without it the payer sees a QR and a number and no sign of what the number
+  # is for; OpenReceive owns no line items, so this is the whole of what it can
+  # show on its own.
+  #
   # TODO(price): look the reference up in your own application, e.g.
   # config.amount_for = lambda do |reference|
   #   order = Order.find_by(id: reference)
-  #   order && { currency: "USD", value: order.total.to_s }
+  #   order && { currency: "USD", value: order.total.to_s,
+  #              description: "#{order.line_items.size} items" }
   # end
 
   # Runs inside the settlement transaction, only for the order's first settled

data/lib/openreceive/configuration.rb

@@ -3,6 +3,14 @@
 require "openreceive/server"
 
 module OpenReceive
+  # The generated initializer's placeholder `config.authorize`: it allows every
+  # request, treating possession of the reference as the authorization. Kept as
+  # a named constant for the same reason LOGGING_ON_PAID is — the engine detects
+  # it at boot and says out loud that anyone holding an order id can mint
+  # invoices, poll status and request refunds for it. The five-minute demo still
+  # works; it just stops being silent.
+  ALLOW_ALL_AUTHORIZE = ->(_context) { true }
+
   class ConfigurationError < StandardError; end
 
   # Passed to the quickstart `config.on_paid` inside the settlement transaction,
@@ -264,9 +272,16 @@ module OpenReceive
     def engine_resolve_checkout
       lambda do |action:, request:, reference:, input:, pay_in_asset: nil|
         pricing = %w[checkout.prepare swap.quote checkout.create swap.create].include?(action)
-        amount = pricing ? @amount_for.call(reference) : nil
-        raise OpenReceive::Server::NotFoundError, "Unknown reference." if pricing && amount.nil?
-        next({ amount: amount }) if %w[checkout.prepare swap.quote].include?(action)
+        price = pricing ? @amount_for.call(reference) : nil
+        raise OpenReceive::Server::NotFoundError, "Unknown reference." if pricing && price.nil?
+        # `description` — what the payer is buying, in the host's own words — is
+        # returned beside the price and peeled off here, so the amount handed to
+        # the minting service stays exactly the price.
+        amount = price_only(price)
+        description = price_description(price)
+        if %w[checkout.prepare swap.quote].include?(action)
+          next({ amount: amount, description: description }.compact)
+        end
 
         requested_hash = input["payment_hash"] || input[:payment_hash]
         begin
@@ -285,6 +300,7 @@ module OpenReceive
 
         {
           amount: amount,
+          description: description,
           payment_hash: payment&.payment_hash,
           checkout: payment&.checkout_data,
           swap_data: payment&.swap_data
@@ -292,6 +308,25 @@ module OpenReceive
       end
     end
 
+    # The price alone. A host that returns a display string beside it must not
+    # have that string reach the amount resolver.
+    def price_only(price)
+      return price unless price.is_a?(Hash)
+
+      price.reject { |key, _| key.to_s == "description" }
+    end
+
+    # One optional display string, blank treated as absent.
+    def price_description(price)
+      return nil unless price.is_a?(Hash)
+
+      value = price[:description] || price["description"]
+      return nil unless value.is_a?(String)
+
+      trimmed = value.strip
+      trimmed.empty? ? nil : trimmed
+    end
+
     def engine_on_checkout_created
       lambda do |reference:, payment_hash:, checkout:, swap_data: nil, client_ip: nil, **|
         begin
@@ -388,6 +423,24 @@ module OpenReceive
       preflight_skip_reason.nil?
     end
 
+    # One line for `bin/rails openreceive:doctor`: did the wallet check pass?
+    #
+    # It builds the service, which is the same eager preflight the engine runs
+    # at production boot — a missing NWC_URI, a dead relay, or a SPEND-CAPABLE
+    # connection all answer here rather than on a payer's first checkout. The
+    # failure is reported, never raised: an operator running a doctor wants
+    # every other line too, and a doctor that dies at line six tells them less
+    # than one that finishes. Sanitized for the same reason the reconcile logs
+    # are — a connect failure can quote the NWC URI, secret and all.
+    def doctor_wallet_report
+      return "skipped — OpenReceive.configure has not run" unless configured?
+
+      config.service
+      "ok — the wallet answered and is receive-only"
+    rescue StandardError => error
+      "FAILED — #{sanitize_failure_message(error)}"
+    end
+
     # nil when the boot preflight should run; otherwise the short reason the
     # engine logs, so an operator who expected a fail-closed boot and did not
     # get one can see why in the same log line.

data/lib/openreceive/engine.rb

@@ -33,6 +33,14 @@ module OpenReceive
             "config/initializers/openreceive.rb."
           )
         end
+        if OpenReceive.config.authorize.equal?(OpenReceive::ALLOW_ALL_AUTHORIZE)
+          ::Rails.logger&.warn(
+            "[openreceive] config.authorize is still the generated allow-all placeholder — " \
+            "anyone holding an order id can mint invoices, poll status, and request refunds " \
+            "for it. Safe only while your references are unguessable. Replace it in " \
+            "config/initializers/openreceive.rb."
+          )
+        end
         if ::Rails.env.production?
           skipped = OpenReceive.preflight_skip_reason
           if skipped.nil?

data/lib/openreceive/rails/version.rb

@@ -5,6 +5,6 @@ module OpenReceive
   # top-level `::Rails` framework constant — engine code always references the framework as
   # `::Rails` to avoid shadowing.
   module Rails
-    VERSION = "0.2.3"
+    VERSION = "0.3.1"
   end
 end

data/lib/tasks/openreceive.rake

@@ -1,6 +1,60 @@
 # frozen_string_literal: true
 
 namespace :openreceive do
+  # Step 0 of the agent directions, as one command.
+  #
+  # "Look for NWC_URI in this app's server environment" is a SEARCH, and it has
+  # a different answer on every host shape: a .env file, Rails credentials, a
+  # deploy config, or — in a containerised app — a value that exists only in the
+  # running process, fetched by a launcher script, where grepping the repo finds
+  # the NAME in a compose file and proves nothing about the value. This asks the
+  # process, which is the only place that always knows.
+  #
+  # PRESENCE ONLY. No secret is ever printed, echoed, or partially shown; every
+  # line is "set" or "unset". That rule is what makes this safe to run in a
+  # shared terminal, paste into an issue, or hand to a coding agent.
+  desc "Report OpenReceive's install state: credentials (set/unset only), engine mount, hooks"
+  task doctor: :environment do
+    set = ->(name) { ENV[name].to_s.strip.empty? ? "unset" : "set" }
+    lines = [
+      "openreceive:doctor",
+      "  NWC_URI:          #{set.call('NWC_URI')}",
+      "  LSC_URI_PRIMARY:  #{set.call('LSC_URI_PRIMARY')}",
+      "  LSC_URI_BACKUP:   #{set.call('LSC_URI_BACKUP')}"
+    ]
+
+    if OpenReceive.configured?
+      config = OpenReceive.config
+      hook = lambda do |value, placeholder, name|
+        return "MISSING — the engine refuses to serve checkouts without it" if value.nil?
+        return "the generated placeholder (#{name}) — replace it" if value.equal?(placeholder)
+
+        "set"
+      end
+      lines << "  configure:        run"
+      lines << "  authorize:        #{hook.call(config.authorize, OpenReceive::ALLOW_ALL_AUTHORIZE,
+                                                'allow-all')}"
+      lines << "  amount_for:       #{config.amount_for.nil? ? 'MISSING — the engine refuses to serve checkouts without it' : 'set'}"
+      lines << "  on_paid:          #{hook.call(config.on_paid, OpenReceive::LOGGING_ON_PAID,
+                                                'logging-only')}"
+    else
+      lines << "  configure:        NOT RUN — run `bin/rails generate openreceive:install`"
+    end
+
+    mount = Rails.application.routes.routes.find do |route|
+      route.app.respond_to?(:app) && route.app.app == OpenReceive::Engine
+    end
+    lines << "  engine mounted:   #{mount.nil? ? 'no — add `mount OpenReceive::Engine` to config/routes.rb' : "at #{mount.path.spec}"}"
+
+    # The wallet check, last and best-effort: it is the only line that talks to
+    # a relay, and a doctor that raises tells an operator less than one that
+    # reports. The receive-only verdict is the whole point — a spend-capable
+    # connection is refused, not warned about.
+    lines << "  wallet preflight: #{OpenReceive.doctor_wallet_report}"
+
+    puts lines.join("\n")
+  end
+
   desc "Run one OpenReceive reconciliation pass over pending payment attempts"
   task reconcile: :environment do
     checks = OpenReceive.reconcile!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - OpenReceive
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.3
+        version: 0.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.3
+        version: 0.3.1
 - !ruby/object:Gem::Dependency
   name: openreceive-server
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.3
+        version: 0.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.3
+        version: 0.3.1
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement