openreceive-server 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d476e033b4974c2349800f3a8aae6b3a097027b912b208dfeffd7a79e9a19b0f
-  data.tar.gz: e6a8d6732c35b93f6414d85c0aec841cc81d400c187c0d7fa50cab817a675614
+  metadata.gz: 500b212ec0e8a9bd58dfa38b19e90ede798db5ded9d1cb5c92d8da2b86ce186c
+  data.tar.gz: bf86d6d2f53a8df863e814a7452968a89d2a941391f024389a52c31a7e3856b5
 SHA512:
-  metadata.gz: 1e86a0afe927a1d99b70f1e1b59c92f1b89622353796f5e0b8a59a5e874eb31e55aa8d2517a17e63d6cb00d167b7e0819f4a2364f10b1668660db36342a0cd55
-  data.tar.gz: 3f00557f4b1aaf1593d3f0ac39d69a35c81c318f80f9e98657d6661bd2e39bcaf047c2dc7bbf7d2d0fcb608e20524eb0bd6a593bd658adf63043197f10d7ac9c
+  metadata.gz: 68a97e57ae6190037bcd5a6251c47db9e343ce3792138644140e1f490ec18c805c06752f9fcacd1e58a52c244564516f10a1d3adeccd5011373da1f2fb2cfce8
+  data.tar.gz: fd7687df474ee570860c72685ca107648f4ae77c56f4e177a3f5d45968463ef7100d0e8db97f1b886c15203178fd7fecd8c2728ecc9aa7d4fe4902be39efa276

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.3.3 - 2026-09-02
+
+### Error messages state the fix and link the doc
+
+The spend-capable refusal now mirrors the Node engine: the receive-only
+framing, the leaked-code-drains-the-wallet rationale, the get-a-code URL, and
+the override spelled `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true` (previously
+`=1`). Wallet preflight failures carry the same URL. The 403 for a denied
+reference names the host's authorize hook and links the authorization guide,
+and the handler's required-hook `ArgumentError`s say how to fix themselves.
+
+### The gem carries the agent skills
+
+`skills/` ships in the gem — the integrate and debug playbooks for coding
+agents, kept byte-identical to the repository tree by
+`npm run generate:skills`.
+
+## 0.3.2 - 2026-08-29
+
+### An overpaid swap deposit is a refund, not a support ticket
+
+`normalize_status` mapped a FixedFloat-compatible `EMERGENCY` carrying `MORE`
+to `attention`, which is terminal and has no refund form. The provider itself
+opens `refund_required` for an overpay and accepts a full `choice=REFUND`, so
+the gem now does the same: `MORE` / `OVER` / `OVERPAID` fall through to
+`refund_required`, and `refund_reason` gains `overpaid` and
+`overpaid_and_late`. The refund returns the whole deposit — the payout is a
+fixed-amount bolt11, so a surplus has nothing to convert into.
+
 ## 0.3.1 - 2026-08-28
 
 No changes to this gem in 0.3.1. It is byte-identical to 0.3.0 and ships to keep

data/lib/openreceive/server/errors.rb

@@ -198,7 +198,8 @@ module OpenReceive
       def initialize(reason)
         super(
           "OpenReceive wallet preflight failed: #{reason} Use a receive-only " \
-          "NWC connection advertising make_invoice and list_transactions."
+          "NWC connection advertising make_invoice and list_transactions. " \
+          "Get one here: #{OpenReceive::NWC_CODE_HELP_URL}"
         )
       end
     end
@@ -206,14 +207,17 @@ module OpenReceive
     # Boot-time refusal: the configured NWC connection advertises spend methods.
     # OpenReceive is receive-only; a spend-capable code in a receive deployment
     # is a live theft risk, so preflight fails closed instead of booting.
+    # Mirrors the JS core formatSpendCapabilityRefusedMessage.
     class SpendCapableWalletError < StandardError
       def initialize(methods)
         super(
-          "The configured NWC connection advertises spend methods " \
-          "(#{Array(methods).join(', ')}). OpenReceive is receive-only; use a " \
-          "receive-only NWC code, or override explicitly with " \
-          "config.allow_spend_capable_wallet = true or " \
-          "OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=1."
+          "This NWC connection is NOT receive-only.\n" \
+          "The wallet info event advertises spend method(s): #{Array(methods).join(', ')}.\n" \
+          "A leaked spend-capable NWC code lets an attacker drain the wallet, " \
+          "so OpenReceive refuses to boot with it.\n" \
+          "Get a receive-only NWC code here: #{OpenReceive::NWC_CODE_HELP_URL}\n" \
+          "If this wallet cannot mint a receive-only code and you accept the risk, set " \
+          "allow_spend_capable_wallet: true (or OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=true)."
         )
       end
     end

data/lib/openreceive/server/request_handler.rb

@@ -30,10 +30,26 @@ module OpenReceive
       # returns nil the limiter fails open for that request.
       def initialize(service:, authorize:, resolve_checkout:, on_checkout_created:, on_paid:,
                      rate_limit: nil, client_ip: nil)
-        raise ArgumentError, "authorize is required" if authorize.nil?
-        raise ArgumentError, "resolve_checkout is required" if resolve_checkout.nil?
-        raise ArgumentError, "on_checkout_created is required" if on_checkout_created.nil?
-        raise ArgumentError, "on_paid is required" if on_paid.nil?
+        if authorize.nil?
+          raise ArgumentError,
+                "authorize is required — authentication belongs to the host application. " \
+                "https://openreceive.org/guides/authorization.md"
+        end
+        if resolve_checkout.nil?
+          raise ArgumentError,
+                "resolve_checkout is required — it resolves a reference to the host-owned " \
+                "amount and attempt. https://openreceive.org/guides/api-reference.md"
+        end
+        if on_checkout_created.nil?
+          raise ArgumentError,
+                "on_checkout_created is required — it persists the attempt before payer " \
+                "instructions are returned. https://openreceive.org/guides/api-reference.md"
+        end
+        if on_paid.nil?
+          raise ArgumentError,
+                "on_paid is required — it durably records settlement. " \
+                "https://openreceive.org/guides/api-reference.md"
+        end
         @service = service
         @authorize = authorize
         @resolve_checkout = resolve_checkout
@@ -350,7 +366,13 @@ module OpenReceive
 
       def authorize!(action, request, resource)
         context = { action: action, request: request, resource: resource }
-        raise ForbiddenError, "Not authorized for this action." unless @authorize.call(context)
+        return if @authorize.call(context)
+
+        # Byte-identical to the JS handler's FORBIDDEN message (same wire contract).
+        raise ForbiddenError,
+              "Not authorized for this action. The application's authorize hook denied it; " \
+              "if this is unexpected, check that the payer's session reaches the checkout " \
+              "routes. https://openreceive.org/guides/authorization.md"
       end
 
       def commit(checkout, swap_data = nil, request = nil)

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

@@ -642,12 +642,11 @@ module OpenReceive
                   "attention_reason" => "provider_reported_emergency"
                 }
               end
-              if (statuses & %w[MORE OVER OVERPAID]).any?
-                return {
-                  "state" => "attention", "attention" => true,
-                  "attention_reason" => "provider_reported_emergency"
-                }
-              end
+              # An overpay (MORE) takes the same self-serve full-refund path as
+              # LESS and EXPIRED — it is what the provider itself does with it.
+              # There is no partial refund of the surplus: the payout invoice is
+              # a fixed amount, so an emergency deposit is returned whole or not
+              # at all.
               result = { "state" => "refund_required" }
               result["refund_reason"] = refund_reason unless refund_reason.nil?
               return result
@@ -662,11 +661,17 @@ module OpenReceive
             }
           end
 
+          # LIMIT rides along with LESS/MORE when the deposit fell outside the
+          # pair's limits. It says nothing the payer can act on beyond the
+          # amount itself, so it names no reason of its own.
           def refund_reason_from_emergency_statuses(statuses)
             less = statuses.include?("LESS")
+            more = (statuses & %w[MORE OVER OVERPAID]).any?
             expired = statuses.include?("EXPIRED")
             return "underpaid_and_late" if less && expired
+            return "overpaid_and_late" if more && expired
             return "underpaid" if less
+            return "overpaid" if more
             return "late_deposit" if expired
 
             nil

data/lib/openreceive/server/version.rb

@@ -2,6 +2,6 @@
 
 module OpenReceive
   module Server
-    VERSION = "0.3.1"
+    VERSION = "0.3.3"
   end
 end

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

@@ -0,0 +1,88 @@
+---
+name: debug-openreceive-payment
+description: >
+  Diagnose a failing OpenReceive integration. Use when an OpenReceive-powered
+  checkout misbehaves: the server refuses to boot, checkout routes return 403,
+  404, 409, or 5xx, a paid invoice never settles, a swap refund seems
+  unreachable, or the checkout UI renders nothing.
+license: MIT
+---
+
+# Debug an OpenReceive payment
+
+Work top-down: configuration, then the request, then settlement. Every guide
+URL below is raw markdown — fetch it when the step needs it.
+
+## 1. Run the doctor first
+
+```sh
+npx openreceive doctor                     # Node version, NWC_URI, swap config, wallet probe
+npx openreceive doctor --db <db>           # + are openreceive_payments/openreceive_meta migrated?
+npx openreceive doctor --url http://localhost:3000   # + are the routes actually mounted?
+```
+
+Each failing line states its own fix. `npx openreceive debug-report` prints the
+same diagnostics redacted, always exit 0 — safe to share.
+
+## 2. Boot failures
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `MISSING_NWC` / "needs a receive-only NWC code" | `NWC_URI` is not in the server process env. A `.env` file alone is not enough — something must load it (`dotenv/config`, Next auto-load). Get a code: https://openreceive.org/get_a_nwc_code_to_receive_payments |
+| `INVALID_NWC` / "not a valid NWC code" | The value is malformed (must be `nostr+walletconnect://` with 64-hex pubkey and secret, ≥1 `wss` relay). Re-copy it from the wallet. |
+| "NOT receive-only" / spend methods advertised | The wallet minted a spend-capable code; OpenReceive fails closed because a leak would drain the wallet. Mint a receive-only code. Overriding (`allowSpendCapableWallet` / `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC`) is a last resort. |
+| Wallet preflight failed (methods/encryption) | The wallet must advertise `make_invoice` + `list_transactions` and NIP-04 or NIP-44 v2. Use a compatible wallet. |
+| "The openreceive_meta table does not exist" / raw `no such table: openreceive_payments` | The migration was never applied. Node: `npx openreceive scaffold payments --orm <yours>`, then run the emitted migration through the app's normal workflow. Rails: `bin/rails generate openreceive:install`, then `bin/rails db:migrate`. https://openreceive.org/guides/storage.md |
+| "requires amountFor / onPaid / authorize / host" | The factory is missing a required hook — see the host contract in https://openreceive.org/guides/api-reference.md |
+
+## 3. Request-time errors from the routes
+
+| Status | Meaning | Where to look |
+| --- | --- | --- |
+| 403 FORBIDDEN | Your own `authorize` hook denied it, or the request looked cross-site. Check the session/cookie actually reaches the checkout routes. https://openreceive.org/guides/authorization.md |
+| 404 NOT_FOUND | `amountFor` returned `null` (unknown reference), or the `payment_hash` does not belong to that reference. |
+| 409 CONFLICT | **Normal state, not a bug**: the reference already settled, or an unpaid checkout for that method is already live. Show it as order state; never retry-loop. |
+| 503 retryable | The host hook failed while persisting the attempt (instructions withheld), or the wallet is unavailable. Read the server log for the underlying error. |
+| Framework 404 / HTML error page | The router is not mounted, or mounted at a different prefix than the UI's `prefix` prop. `doctor --url` distinguishes these. |
+
+## 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
+  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
+  plus a 900s grace constant — a local clock alone never closes one. `expired`
+  arriving "late" is correct.
+- `onPaid` runs once per reference, first settled attempt only, inside the
+  settlement transaction. If your fulfillment did not run, check whether the
+  guarded `UPDATE … WHERE` matched zero rows (already transitioned).
+  https://openreceive.org/guides/storage.md
+
+## 5. Swaps and refunds
+
+- A deposit that arrives short or late becomes `refund_required`; the payer
+  claims it on a second visit. That needs a per-order URL you serve
+  (`/checkout/:reference`, `syncUrl` on the drop-ins). Keep the
+  `payment_hash`: `POST /swaps/status` reopens the attempt with no expiry
+  window, while re-picking the coin mints a new deposit after ~30 minutes.
+- Refunds exist only for swap deposits from `refund_required`. There is **no
+  Lightning refund** — the wallet cannot spend. Do not chase one.
+  https://openreceive.org/guides/swap-refunds.md
+
+## 6. Checkout UI shows nothing
+
+- The components require `prefix` — the exact base path the routes are mounted
+  at (`"/openreceive"` unless you changed it).
+- Import the stylesheet (`@openreceive/react/styles.css` or the elements
+  sheet).
+- "invoice must not be an NWC connection string" means a server secret leaked
+  into a browser payload — stop and fix the server response; never render it.
+  https://openreceive.org/guides/frontend-checkout.md
+
+## Still stuck
+
+The full route/option/error reference:
+https://openreceive.org/guides/api-reference.md · machine-readable contract:
+https://openreceive.org/openapi.yaml · library bug reports:
+https://openreceive.org/contact

data/skills/integrate-openreceive/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: integrate-openreceive
+description: >
+  Integrate OpenReceive inbound Bitcoin Lightning payments into an application.
+  Use when adding Bitcoin, Lightning, or crypto checkout to a Node.js, Express,
+  Fastify, Next.js, Rails, React, Vue, Svelte, Angular, or plain-HTML
+  application with OpenReceive (the @openreceive/* npm packages or the
+  openreceive-rails gem).
+license: MIT
+---
+
+# Integrate OpenReceive
+
+OpenReceive is a payment library that runs inside the application you are
+editing. It mounts HTTP routes there, issues Lightning invoices against a
+wallet the merchant already controls, and calls back into your code when one
+settles. There is no OpenReceive account and no API key; funds land directly in
+the merchant's wallet. The one required credential is a **receive-only NWC
+code** (`NWC_URI`).
+
+## Pick the stack, then follow its directions
+
+1. Identify the server stack of the application you are in.
+2. Open the matching reference — it is complete (quickstart inlined) and needs
+   no network access:
+   - Node (Express / Fastify / Next.js): [references/node.md](references/node.md)
+   - Rails: [references/rails.md](references/rails.md)
+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.
+
+Install (Node): `npm install @openreceive/express @openreceive/react` — swap
+the adapter (`fastify`, `next`) and UI package (`vue`, `svelte`, `angular`,
+`elements`) for the stack. Install (Rails): `bundle add openreceive-rails`.
+
+## The three server objects
+
+| Object | Built with | Talks to |
+| --- | --- | --- |
+| Wallet client | `createOpenReceive()` | the merchant's wallet — mints invoices, reads settlement, holds the NWC code |
+| Host | `createHost()` | your database — your hooks plus the `openreceive_payments` table |
+| HTTP routes | `openReceiveExpress()` / `openReceiveFastify()` / `openReceiveNext()` / the Rails engine | the browser — mounted at `/openreceive` by default |
+
+The quickstart's one-factory form (`openReceiveExpress({ wallet, storage,
+amountFor, authorize })`) builds all three; compose them separately only for a
+shared wallet client or a custom repository. The checkout UI
+(`<Checkout reference={...} prefix="/openreceive" />`) is the optional fourth
+piece.
+
+## The host contract: authorize, amountFor, onPaid
+
+Your application keeps orders, users, prices, and fulfillment. Three hooks are
+the entire bridge — wire them to the models this app already has, never to
+copied demo models:
+
+- `amountFor(reference)` — the authoritative price, read from your own data.
+  Return `{ currency, value, description }` with `value` a **decimal string**
+  (never a float, never payer input), or `null` when there is nothing to pay
+  for. The `reference` is your order id: one per thing you fulfill, created
+  before checkout, kept across retries, never reused.
+- `authorize({ action, request, resource })` — your own access check, run on
+  every request. `resource.reference` is a claim the payer made, not proof;
+  read a real session.
+- `onPaid({ reference, paidAt, query })` — fulfillment, run once per reference
+  inside the settlement transaction, only for the first settled attempt. Use
+  the provided `query`, not your ORM's other connection, and guard the
+  transition (`UPDATE … WHERE state = 'awaiting_payment'`).
+
+## 409 is a state, not a failure
+
+The library serializes attempts per reference. A create that returns **409
+CONFLICT** is normal checkout flow: the reference already settled, or an unpaid
+checkout for that payment method is already in progress. Surface it as order
+state; do not retry-loop it, and do not build an idempotency store around it —
+that serialization is the library's job. (A hook failure while persisting an
+attempt is a **503 retryable**, deliberately distinct.)
+
+## Secrets
+
+`NWC_URI` and `LSC_URI_*` are server-only. Never put them in browser code,
+logs, assets, or tests. Boot fails closed if the NWC code advertises spend
+methods such as `pay_invoice` — mint a receive-only code
+(https://openreceive.org/get_a_nwc_code_to_receive_payments) instead of
+overriding.
+
+## Database tables
+
+```sh
+npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
+```
+
+emits the `openreceive_payments` + `openreceive_meta` migration for THIS app's
+database (Rails: `bin/rails generate openreceive:install`); run it through the
+app's normal migration workflow. The tables sit beside your models — no
+relations to them, no separate database, no Redis.
+
+## Verify, and test without a real wallet
+
+`npx openreceive doctor` checks the configuration and says what to fix.
+
+For tests, inject a fake wallet at the stable seams — `client` on
+`createOpenReceive` (any object with `preflight`, `makeInvoice`,
+`listTransactions`) or `config.nwc_client` in Rails — plus
+`StaticPriceProvider` for fiat pricing without a network. Your routes,
+persistence, reconcile, and `onPaid` then run the production code paths.
+Details: https://openreceive.org/guides/host-testing.md
+
+## Deeper documentation
+
+Fetch on demand — each URL is raw markdown:
+https://openreceive.org/guides/authorization.md ·
+https://openreceive.org/guides/storage.md ·
+https://openreceive.org/guides/api-reference.md ·
+https://openreceive.org/guides/security.md ·
+https://openreceive.org/openapi.yaml (the normative HTTP contract) ·
+https://openreceive.org/llms.txt (the full index)