openreceive-server 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69c84c3c9d2c89bf54eb2a69b10560be5f5b51bdadc38fed124d47a43c737bf5
-  data.tar.gz: 7bba81aa2ae40c14a41fd8ec713b3aae342f1f87e46be107668c01271dd82997
+  metadata.gz: 1e4751e31d676760c9be4378fb54984746caa21409f15d80b9f1a102e7841e9b
+  data.tar.gz: f75da1316d4bed7802dd3f1412ac173ddaee70a8edc482b47c7cc1d94026ea02
 SHA512:
-  metadata.gz: 7e57669e81f47d6df8941ba953cdc6791f125bbad010f2e9a3f7cd6968ddb626afeb1d6fd608bdb893573fe0981f0a7d19fe75e0739eef1594cf00cfe319a3af
-  data.tar.gz: 62b051babf8198b51de547e7c7535803f0fa658df930efea0e69205c3a3bbef733116681944758780c822a8046c185f5f9782cc80c7abf9dcbf182d5227c915e
+  metadata.gz: 1e85465cf41f32f4997db65be55786005b275762793eac68eaae9c885c663cdf840f715e5a54efa71cd604e2eaa0e565d0e1a040d4fb534c844a43110f5ad1af
+  data.tar.gz: 1178a6c56c2ac21013ef5ce2ae8843dc21cf3e5b742dbbe89bafdbd903069f39b8a8cece4305b984a23bed787751131aaeec5f8ba139ecf93f24e622e35a18ec

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.0 - 2026-09-02
+
+Version lockstep with the 0.4.0 npm release. The README's `authorize` example
+now states the resource guarantee: `context[:resource][:reference]` is always a
+validated non-empty String (200 characters or fewer) by the time the hook runs,
+and `payment_hash` is nil except on `payment.check`, `swap.read`, and
+`swap.refund`. No functional change.
+
+## 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

data/README.md

@@ -21,7 +21,9 @@ run OpenReceive::Server::RackApp.new(
   # context is a Hash: context[:action] is the route name ("checkout.create",
   # "payment.check", …), context[:request] is the Rack env, and
   # context[:resource] is { reference:, payment_hash: } copied from the
-  # payer's body — it names an order, it does not prove ownership.
+  # payer's body — it names an order, it does not prove ownership. reference
+  # is always a validated non-empty String (≤200 chars); payment_hash is nil
+  # except on payment.check / swap.read / swap.refund.
   # Return true to allow, false for a 403.
   authorize: ->(context) { my_policy_allows?(context) },
   resolve_checkout: lambda do |action:, request:, reference:, input:, pay_in_asset: nil|

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/version.rb

@@ -2,6 +2,6 @@
 
 module OpenReceive
   module Server
-    VERSION = "0.3.2"
+    VERSION = "0.4.0"
   end
 end

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

@@ -0,0 +1,89 @@
+---
+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 |
+| Never 403s — any visitor can mint, poll, or refund for any reference | The opposite failure: on Rails the generated `config.authorize = OpenReceive::ALLOW_ALL_AUTHORIZE` placeholder is still installed (the engine warns at boot; `bin/rails openreceive:doctor` reports it). Replace it with the app's real ownership check. 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)