openreceive-rails 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 146123aec012ee584a8b76fd2a0377abb9e972fafd56f5332e67deee15fc7ad3
-  data.tar.gz: d38a035c403bffa06b058ed1030a7bb55170cce1e9853c26d8ff71d4698ec6be
+  metadata.gz: e7ef5df95a3cc1af66502a65a1b130aad1a88ab8ff93dcd26b4e93a1d732dca2
+  data.tar.gz: 291e45e4efa083eee2345490086e97e757ae3009aa0f79ba3a7ef3ba55a04bb5
 SHA512:
-  metadata.gz: 4703f944a363b826d607c7e63a3e918fb76465e5e260f54bc59a00e2e84b316ebdfd5909a91943a1bf3e7ce92051216b0c7f35b61a2e6b17a66cf20b81f3e92a
-  data.tar.gz: 9b13db6baea87e02685030ef09ec88f741c3bd18b13b30a54189d43e2c3ecb9ba2b7e656c93b1aff2c80bd321d99bd96aebfc99eae0046b8ab0873e914fa0126
+  metadata.gz: 36a33f19c0791f0e127c7cb4bc6b746aa377a124d5e1c9cef9c553826416f6fb51383029c0b8ba1b0ad11e33e4b069e3156bff2d751adbafe0718825c99a9105
+  data.tar.gz: 18e1177d9a7974614eb8db63fe27c5414b21a0758c7e2f4f02d4e955970403217ebf6bbf3c94e1d7d840219ba99cdaf944f4bc0e64ad395fc7318937fef5e85f

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.3.2 - 2026-08-29
+
+No changes to this gem in 0.3.2. The release is the overpaid-deposit refund
+mapping in `openreceive-server` and the browser packages' `resumePaymentHash`
+resume path; the engine, its generators and the doctor task are byte-identical
+to 0.3.1 and ship to keep the one-version-for-everything rule.
+
+The Rails demo at `examples/buttons/server/rails` gained a testkit mode and a
+`/checkout/:reference` route in this release. Neither is part of this gem.
+
+## 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

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

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,
@@ -415,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.3.0"
+    VERSION = "0.3.2"
   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.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - OpenReceive
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: openreceive-server
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement