@rozoai/checkout 0.1.0 → 0.1.2

package/docs/how-it-works.md

@@ -0,0 +1,43 @@
+# How it works
+
+[← back to the README](../README.md) · [Quick start](QUICKSTART.md) · [Safety design](safety.md)
+
+```mermaid
+flowchart TD
+    A["Coinbase Payment Link<br/>payments.coinbase.com/payment-links/pl_*"] --> B
+    B["quote-invoice<br/>(public POST)"] --> C["create-invoice<br/>(public POST)"]
+    C --> D["Bridge order<br/>one-time deposit address<br/>+ exact amount + expiry"]
+    D --> E["You send USDT/USDC/BTC<br/>on your chosen chain"]
+    E --> F["Bridge converts the pay-in"]
+    F --> G["Funder wallet settles<br/>the Coinbase invoice"]
+    G --> H["Merchant is paid<br/>(e.g. OpenRouter credit)"]
+```
+
+The same thing as ASCII, for terminals without mermaid:
+
+```
+  Coinbase Payment Link (pl_* / paymentSession_*)
+            |
+            v
+  [ quote-invoice ]  ->  merchant, amount, expiry, short-lived quote receipt
+            |
+            v
+  [ create-invoice ] ->  bridge order:  rozoPaymentId + deposit address
+            |                            + exact amount + order expiry
+            v
+  you send USDT / USDC / BTC on your chain  ------> deposit address
+            |
+            v
+  bridge converts the pay-in  ------>  funder wallet pays the Coinbase invoice
+            |
+            v
+  merchant credited; poll until the state is `settled`
+```
+
+Three identifiers appear throughout and are never interchangeable:
+
+| Identifier | What it is |
+|---|---|
+| `linkId` | the Coinbase id: `pl_*` (Payment Link) or `paymentSession_*` (v3 session) |
+| `rozoPaymentId` | the bridge order's UUID — use this for deposit detail and status |
+| `paymentLink` | a hosted pay page URL for the bridge order (human fallback) |

package/docs/safety.md

@@ -0,0 +1,78 @@
+# Safety design
+
+[← back to the README](../README.md) · [Quick start](QUICKSTART.md) · [How it works](how-it-works.md)
+
+The interesting part of this project is what it refuses to do. The README keeps
+the three rules a payer needs; everything below is the full list, for anyone
+reviewing or extending the code.
+
+- **Two-phase confirmation, enforced.** `create-order.js` withholds the full
+  deposit address, memo and BOLT11 until it is re-run with `--confirm`, which
+  records a confirmation bound to a sha256 of those exact instructions. The
+  send scripts refuse without both `--send` and a confirmation whose digest
+  still matches the live data, so neither an accidental invocation nor a
+  swapped deposit address can move funds.
+- **Full invoice, always.** `callerPays` must equal the invoice amount and
+  `discount` must be `"0"`; anything else aborts with `NO_DISCOUNT_VIOLATION`.
+  Security-critical fields (`linkId`, `merchant`, `original`, `callerPays`, the
+  echoed source) must be present as well as equal — a missing field is drift.
+- **Reuse guard.** Creating an order for a link that already has an unexpired
+  order returns that existing order — even if it has already been funded. So on
+  every run the live order is required to be unpaid (`payment_unpaid`, no tx
+  hash, no amount received, no confirmation) and to match the chain and token
+  the caller chose. Otherwise: `ORDER_ALREADY_FUNDED` or
+  `REUSED_SOURCE_MISMATCH`.
+- **Money-detected rule, fail closed.** Once any pay-in exists, the tooling
+  never reports a plain failure, never advises paying again, and never retries
+  into a new order. An `amountReceived` that is non-null but unreadable counts
+  as money, not as absence of money. An unreadable backend reports `unknown`,
+  never `awaiting_deposit`.
+- **Complete deposit instructions.** A zero, negative or unparsable amount
+  aborts. Lightning requires the BOLT11 (which arrives in `source.lnInvoice`
+  with an empty address). A Stellar deposit is a shared hub address plus a
+  per-order memo, so the memo is part of the destination: an order that
+  arrives without one is a hard abort, never rendered as "no memo required".
+- **Expiry margins.** Payment is refused unless the earlier of the order expiry
+  and the Coinbase expiry is more than a per-chain margin away (10 min EVM and
+  Stellar, 5 min Solana). Lightning additionally requires at least 10 minutes
+  of BOLT11 validity. A missing or unparsable deadline aborts.
+- **Payability revalidation.** A quote receipt makes order creation skip the
+  live Coinbase check, and the link can be consumed by someone else at any
+  moment — so payability is re-checked immediately before the deposit address
+  is shown, and again as the very last step before broadcast, after all the RPC
+  preparation. Incomplete Coinbase state is treated as "cannot prove payable",
+  not as payable.
+- **Compromised-address list, fail closed.** `scripts/src/lib/blacklist.json`
+  carries a vendored list with a provenance header and a sha256 over the
+  addresses. The digest proves only that this vendored copy has not been edited
+  since its sync date; it is not a signature by the upstream source. Both the
+  deposit address and the sending wallet are checked. If the file is missing,
+  malformed, empty, or its digest does not match, every send is refused rather
+  than proceeding unchecked.
+- **Send-once, across processes.** Order state lives in
+  `$HOME/.rozo-checkout/state/<uuid>.json`, written atomically (temp file,
+  fsync, rename). Every read-modify-write of a state file — the claim, the
+  spend caps, the order record and the confirmation — runs inside one exclusive
+  lockfile, so two concurrent invocations can neither both decide they are
+  first, nor overwrite each other's send record. A send is claimed *before* broadcasting, so an ambiguous RPC error can
+  never become a second transfer. Transactions are signed before broadcast so
+  the hash is known in advance; on an ambiguous result the scripts look that
+  exact transaction up instead of rebroadcasting.
+- **Hot-wallet controls.** A signing key is read from a local key file (a
+  solana-keygen keypair, or an encrypted V3 keystore whose passphrase is
+  prompted) or from the environment for unattended runs. A key file that is
+  readable by other users, or tracked by git, is refused — as is a `.env`
+  carrying the same settings, which is parsed as plain text and never
+  evaluated by a shell. Keys and passphrases
+  are never accepted on the command line, and are never printed; library and RPC errors are redacted
+  before display, including credential-bearing provider URLs, bearer tokens and
+  key-shaped strings. The scripts refuse to run when any `.env`/`.env.*` in the
+  working directory is git-tracked, and refuse just as hard when git cannot
+  prove it is untracked. The RPC's chain id (or Solana genesis hash) and the token's
+  on-chain decimals are verified before signing. One limit applies: a single
+  payment may not exceed $1,100. There is no override flag and no cumulative
+  session cap — a larger invoice is paid from your own wallet, which needs no
+  key and has no limit.
+- **Address masking.** Prose shows `first6...last4`. The full deposit address,
+  memo and BOLT11 string appear only inside the machine-readable `deposit`
+  object, so they stay copy-pastable without being scattered through logs.

package/llms.txt

@@ -8,7 +8,7 @@
 > deposit normally carries a small bridge/source-chain fee on top.
 
 This file teaches the whole flow to any agent or script. Repo (scripts, safety rails,
-full docs): https://github.com/RozoAI/rozo-checkout-skill — see QUICKSTART.md.
+full docs): https://github.com/RozoAI/rozo-checkout-skill — see docs/QUICKSTART.md.
 
 ## Fastest path: the CLI (npm @rozoai/checkout)
 
@@ -21,11 +21,49 @@ calls with every safety rule already enforced:
 
 --with accepts usdt-solana, usdc-solana, usdt-bnb, usdc-bnb, usdt-ethereum,
 usdc-ethereum, usdt-polygon, usdc-polygon, usdc-base, usdc-stellar, btc-lightning
-(or raw: --chain 900 --token USDT). Flags: --send (pay from a hot wallet, keys from
-ROZO_CHECKOUT_EVM_KEY / ROZO_CHECKOUT_SOL_KEY, never from argv), --yes (skip the
-interactive confirm; required when stdin is not a TTY), --dry-run, --json (exactly
-one JSON object on stdout), --no-watch, --timeout <s>. Exit codes: 0 success,
-1 refused/failed (read error.code), 2 usage, 3 submitted but unconfirmed.
+(or raw: --chain 900 --token USDT).
+
+DEFAULT PATH NEEDS NO KEY: `pay` prints a deposit address for the user to pay from
+any wallet. No private key, no environment variable, no configuration. Only the
+optional --send flag signs locally. Its key comes from the first source that
+exists: --keyfile <path>; then ~/.config/solana/id.json (the keypair
+solana-keygen already wrote) for Solana or ROZO_CHECKOUT_EVM_KEYSTORE (an
+encrypted V3 keystore, passphrase prompted, never argv) for EVM; then a raw key
+in ROZO_CHECKOUT_SOL_KEY / ROZO_CHECKOUT_EVM_KEY, which is the unattended-
+automation option. Those settings may also come from a .env in the working
+directory (or --env-file <path>): only ROZO_CHECKOUT_* keys are read from it, it
+is parsed as text and never shell-evaluated, and the real environment wins.
+Key files and .env must be chmod 600 and untracked by git.
+
+## Local wallet setup for --send (not needed for the default keyless path)
+
+.env keys (only ROZO_CHECKOUT_* are read; real env wins; chmod 600; gitignore):
+  ROZO_CHECKOUT_SOL_KEY               base58 string OR JSON byte array
+  ROZO_CHECKOUT_EVM_KEY               64 hex chars, 0x prefix optional
+  ROZO_CHECKOUT_EVM_KEYSTORE          path to an encrypted V3 keystore
+  ROZO_CHECKOUT_KEYSTORE_PASSPHRASE   unattended runs only; else prompted
+  ROZO_CHECKOUT_RPC_<chainId>         e.g. ROZO_CHECKOUT_RPC_8453 (Base),
+                                      ROZO_CHECKOUT_RPC_900 (Solana)
+
+Where the material comes from:
+- Solana: `solana-keygen new` -> ~/.config/solana/id.json, found automatically
+  (preferred). Phantom exports base58; Solflare exports base58 (current) or a
+  JSON byte array (older). Both accepted.
+- EVM: MetaMask/Rabby export 64 hex chars with no 0x prefix; paste as-is, the
+  prefix is optional. For an encrypted keystore, Foundry's
+  `cast wallet import <name> --interactive` writes a V3 keystore to
+  ~/.foundry/keystores/<name>; `geth account import` also writes one. Browser
+  wallets do not export keystores, only raw keys.
+- Hardware wallets, WalletConnect-only wallets and exchange accounts CANNOT be
+  used with --send. Those users take the default keyless path, which works with
+  any wallet.
+With --send, one limit applies: a single payment may not exceed $1,100, with no
+override; larger invoices go through the keyless path.
+
+Other flags: --yes (skip the interactive confirm; required when stdin is not a
+TTY), --dry-run, --json (exactly one JSON object on stdout), --no-watch,
+--timeout <s>. Exit codes: 0 success, 1 refused/failed (read error.code),
+2 usage, 3 submitted but unconfirmed.
 
 `pay` withholds the full deposit address until you confirm, then prints it as a
 copy-pastable block. Creating an order moves no money; an unfunded order expires.
@@ -38,6 +76,12 @@ chainId "1" Ethereum (USDC, USDT) · "56" BNB Chain (USDC, USDT; 18-decimals) ·
 amounts in integer satoshis via source.amountUnit=="sats").
 Native SOL/ETH/BNB are NOT supported — stablecoins (or Lightning BTC) only.
 
+WALLET: one wallet on one of these chains is enough — not one per chain. Any
+wallet, or an exchange withdrawal, can fund the deposit address; nothing
+connects to a site. Stellar is the exception that must be able to set a memo,
+and Lightning pays a BOLT11 invoice rather than an address. Only --send needs a
+private key (EVM and Solana only); every other path is keyless.
+
 ## Flow (4 HTTP calls, all public)
 
 1) Quote (read-only, safe):
@@ -62,7 +106,9 @@ Native SOL/ETH/BNB are NOT supported — stablecoins (or Lightning BTC) only.
    -> { status, expiresAt, source:{ receiverAddress, receiverMemo, amount, amountUnit,
         lnInvoice, txHash, amountReceived, confirmedAt, ... }, destination:{...} }
    Pay EXACTLY source.amount of the requested token on the requested chain to
-   source.receiverAddress (include receiverMemo when present — Stellar requires it).
+   source.receiverAddress, including every other field the block carries (Stellar
+   routes on a shared hub address plus source.receiverMemo, so omitting the memo
+   loses the payment).
    For Lightning, pay the BOLT11 in source.lnInvoice (receiverAddress is empty).
 
 4) Poll until settled:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozoai/checkout",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Pay an OpenRouter Coinbase Payment Link with BTC Lightning, or USDT/USDC on Solana, BNB Chain, Ethereum, Polygon, Base or Stellar.",
   "license": "MIT",
@@ -28,15 +28,10 @@
   },
   "files": [
     "scripts/dist",
+    "docs/*.md",
+    "!docs/reviews",
     "llms.txt",
     "README.md",
-    "README.zh.md",
-    "README.ja.md",
-    "README.es.md",
-    "QUICKSTART.md",
-    "QUICKSTART.zh.md",
-    "QUICKSTART.ja.md",
-    "QUICKSTART.es.md",
     "LICENSE"
   ],
   "engines": {