@rozoai/checkout 0.1.0 → 0.1.1

package/docs/README.ja.md

@@ -0,0 +1,255 @@
+# rozo-checkout
+
+[English](../README.md) | [简体中文](README.zh.md) | **日本語** | [Español](README.es.md)
+
+**OpenRouter の Coinbase 決済リンク (Payment Link)** を、そのリンクが直接受け取れない
+通貨で支払います — Lightning 経由の BTC、または Solana、BNB Chain、Ethereum、
+Polygon、Base、Stellar 上の USDT/USDC です。Coinbase の決済リンクは Base 上の USDC しか
+受け付けません。本ツールは、あなたが実際に保有している通貨をブリッジ経由で中継し、
+資金提供ウォレット (funder wallet) があなたに代わってインボイスを決済します。
+アカウントも API キーもブラウザーも不要です。
+
+```bash
+npx @rozoai/checkout pay <coinbase-link>
+```
+
+どの通貨で支払うかを最初に尋ねます。プロンプトでウォレットアドレスを貼り付けると、
+どの通貨なら残高が足りるかを表示します。そのあと、任意のウォレットから支払うための
+入金アドレスが表示されます — **秘密鍵も環境変数も設定も一切不要です**。あとは
+インボイスが決済完了するまで待つだけです。
+
+使う通貨が決まっている場合は、この質問を省略できます:
+
+```bash
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+## 支払いに使える通貨
+
+| チェーン | `--with` | チェーン id | 備考 |
+|---|---|---|---|
+| Ethereum | `usdt-ethereum` `usdc-ethereum` | `1` | 小数点以下 6 桁 |
+| BNB Chain | `usdt-bnb` `usdc-bnb` | `56` | 小数点以下 18 桁 |
+| Polygon | `usdt-polygon` `usdc-polygon` | `137` | 小数点以下 6 桁 |
+| Base | `usdc-base` | `8453` | 小数点以下 6 桁 |
+| Solana | `usdt-solana` `usdc-solana` | `900` | SPL。ネイティブの SOL は非対応 |
+| Stellar | `usdc-stellar` | `1500` | メモが必須 — 入金ブロックに表示されます |
+| Bitcoin Lightning | `btc-lightning` | `lightning` | BOLT11。金額は satoshi 単位 |
+
+ネイティブのガス通貨（SOL、BNB、ETH、MATIC）およびオンチェーンの BTC は受け付けません。
+
+## エージェントから使う
+
+渡す内容はどこでも同じです。上のワンライナーそのものか、エージェントに
+[llms.txt](../llms.txt) を読ませるかのどちらかです。**自分のウォレットから支払う場合、
+鍵は一切不要です。** ローカルで署名するのは任意の `--send` フラグだけで、
+`ROZO_CHECKOUT_EVM_KEY` / `ROZO_CHECKOUT_SOL_KEY` を読むのもそのフラグだけです。
+エージェントやスクリプトでは必ず `--with` を渡してください。対話式の選択は端末でのみ
+表示され、既定の通貨は意図的にありません。
+
+<details>
+<summary><b>Claude Code</b> — スキルをインストールするか、ワンライナーを貼り付ける</summary>
+
+このリポジトリは Claude Code のスキルです。`SKILL.md` と `scripts/dist/` 内の実行可能
+ファイルが同梱されています。スキルディレクトリにクローンすれば、Claude Code が自動的に
+認識します。
+
+```bash
+git clone https://github.com/RozoAI/rozo-checkout-skill ~/.claude/skills/rozo-checkout
+```
+
+インストールせずに、実行を依頼するだけでも構いません:
+
+```
+この OpenRouter のリンクを Solana の USDT で支払ってください:
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Claude にホットウォレット
+から署名させたい場合にだけ `--send` を追加してください。その場合は環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>Codex CLI</b> — AGENTS.md に書くか、そのまま実行する</summary>
+
+Codex はプロジェクトルートの `AGENTS.md` を読みます。毎回説明しなくても支払い方が
+分かるように、常設の指示を追加しておきましょう:
+
+```
+OpenRouter / Coinbase の決済リンクを支払うには、次を実行してください:
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>OpenCode</b> — AGENTS.md に書くか、そのまま実行する</summary>
+
+OpenCode もプロジェクトルートの `AGENTS.md` を読むため、上の Codex 用のスニペットが
+そのまま使えます。最短経路はやはりコマンドそのものです:
+
+```bash
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>Cline</b> — .clinerules に書くか、そのまま実行する</summary>
+
+Cline はプロジェクトルートの `.clinerules` から常設の指示を読み込みます:
+
+```
+OpenRouter / Coinbase の決済リンクを支払うには、次を実行してください:
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>Cursor</b> — .cursor/rules に書くか、そのまま実行する</summary>
+
+`.cursor/rules/rozo-checkout.mdc` にプロジェクトルールを追加します:
+
+```
+OpenRouter / Coinbase の決済リンクを支払うには、次を実行してください:
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>Hermes Agent</b> — セッション内でワンライナーを実行する</summary>
+
+Hermes Agent（Nous Research）はシェルにアクセスでき、独自のスキルシステムを持っています。
+`hermes` で起動して、こう依頼してください:
+
+```
+https://checkout.rozo.ai/llms.txt を取得したうえで、この OpenRouter のリンクを支払ってください:
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>OpenClaw</b> — openclaw agent exec</summary>
+
+OpenClaw のヘッドレス入口は単発のタスクを実行するため、スクリプトやチャットチャンネル
+から起動する支払いに向いています:
+
+```bash
+openclaw agent exec "Pay this OpenRouter link with USDT on Solana by running: npx @rozoai/checkout pay <coinbase-link> --with usdt-solana"
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>Pi</b> — セッション内でワンライナーを実行する</summary>
+
+Pi は BYOK のターミナルエージェントで、組み込みツールに `bash` を含むため、コマンドを
+直接実行できます。`pi` で起動して、こう依頼してください:
+
+```
+この OpenRouter のリンクを Solana の USDT で支払ってください。次を実行します:
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+<details>
+<summary><b>ターミナル — エージェントなし</b> — スクリプトを 1 ステップずつ実行する</summary>
+
+各ステップを自分で進めます。バンドルは自己完結型なので、Node 18 以降のほかに
+インストールするものはありません。
+
+```bash
+git clone https://github.com/RozoAI/rozo-checkout-skill && cd rozo-checkout-skill
+LINK="https://payments.coinbase.com/payment-links/pl_01YOURLINKID"
+
+# 読み取り専用の見積もり。費用はかかりません
+node scripts/dist/quote.js --url "$LINK"
+
+# 注文を作成します。ここでは完全な入金アドレスは伏せられ、まず確認用の
+# マスクされた要約が返ります。
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT
+
+# 支払うと決めたら、--confirm を付けて再実行し、アドレスを開示します
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confirm
+
+# 入金ブロックの内容を任意のウォレットから支払い、決済完了を見守ります
+node scripts/dist/status.js --rozo-payment-id <uuid> --watch
+```
+
+各スクリプトは標準出力にちょうど 1 個の JSON オブジェクトを出力します。終了コードは
+`0` が成功、`1` が拒否/失敗（`error.code` を参照）、`2` が使い方の誤り、`3` が送信済みだが
+未確認です。詳しい手順: [クイックスタート](QUICKSTART.ja.md)。
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** ホットウォレットからの送金
+については、`ROZO_CHECKOUT_EVM_KEY` / `ROZO_CHECKOUT_SOL_KEY` を読む `send-evm.js` /
+`send-sol.js` を参照してください。
+</details>
+
+<details>
+<summary><b>その他のあらゆるエージェント</b> — llms.txt を読ませる</summary>
+
+URL を取得してコマンドを実行できるエージェントであれば、どれでもこれができます:
+
+```
+https://checkout.rozo.ai/llms.txt を自分のコンテキストに読み込み、それを使って
+この OpenRouter のリンクを支払ってください: <coinbase-link>
+```
+
+シェルを持たないエージェントでも、HTTP リクエストが可能なら 4 つの公開エンドポイントを
+直接操作できます — [仕組み](how-it-works.md) を参照してください。
+
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+環境変数の鍵が必要です。
+</details>
+
+## 知っておく価値のある 3 つのルール
+
+- **入金アドレスは使い捨てです。** 古い注文、キャッシュされたレスポンス、スクリーンショット
+  から得たアドレスを再利用しては決していけません。
+- **表示された金額をそのとおりに送金してください。** 通常はインボイス金額より大きくなります
+  — ブリッジ手数料とネットワーク手数料が含まれるためです。
+- **入金済みの注文に二重に支払っては決していけません。** すでに支払いが検知されている場合は
+  中止し、人間に照合を依頼してください。使い捨てアドレスへの 2 回目の支払いは、入金として
+  反映される保証がありません。
+
+本ツールが何を拒否するのか、そしてその理由の完全な一覧は
+[safety.md](safety.md) にあります。
+
+## リンク
+
+- [クイックスタート](QUICKSTART.ja.md) — 5 つのコマンドと、期待される出力
+- [仕組み](how-it-works.md) — フロー、エンドポイント、識別子
+- [安全性の設計](safety.md) — すべての安全機構の詳細
+- [SKILL.md](../SKILL.md) — エージェント向けの指示書 · [llms.txt](../llms.txt) — 1 ファイルの要約
+- [checkout.rozo.ai/agent](https://checkout.rozo.ai/agent.html) — 同じものを Web で
+- [Issues](https://github.com/RozoAI/rozo-checkout-skill/issues) — バグと要望
+
+## 変更履歴
+
+- **0.1.1** — 支出上限を 2 つから 1 つに変更しました。1 回の支払いは $1,100 を超えられず
+  （$1,000 のクレジット購入とその 5% の手数料に合わせた値です）、セッション累計の上限と
+  `--yes-large` による上書きは削除されました。自分のウォレットから支払う場合は鍵も設定も
+  不要であることを、ドキュメントで明示しました。
+- **0.1.0** — 最初のリリース: `npx @rozoai/checkout`。
+
+## ライセンス
+
+MIT.

package/docs/README.zh.md

@@ -0,0 +1,233 @@
+# rozo-checkout
+
+[English](../README.md) | **简体中文** | [日本語](README.ja.md) | [Español](README.es.md)
+
+用一种 **OpenRouter Coinbase 收款链接 (Payment Link)** 本身收不了的币去付款 —— 走
+闪电网络的 BTC，或者 Solana、BNB Chain、Ethereum、Polygon、Base、Stellar 上的
+USDT/USDC。Coinbase 收款链接只接受 Base 上的 USDC；本工具把你实际持有的币通过
+一座桥路由过去，再由一个出资钱包代你结清账单。无需账号、无需 API key、无需浏览器。
+
+```bash
+npx @rozoai/checkout pay <coinbase-link>
+```
+
+它会先问你想用哪种币付款 —— 在提示处粘贴你的钱包地址，它就会标出哪些币你余额
+够付 —— 然后打印一个充值地址，你用任意钱包付进去即可 —— **不需要私钥、不需要
+环境变量、不需要任何配置**。之后它会一直等到账单被结清。
+
+已经知道要用哪种币？直接跳过这一问：
+
+```bash
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+## 可用于付款的币种
+
+| 链 | `--with` | 链 id | 备注 |
+|---|---|---|---|
+| Ethereum | `usdt-ethereum` `usdc-ethereum` | `1` | 6 位小数 |
+| BNB Chain | `usdt-bnb` `usdc-bnb` | `56` | 18 位小数 |
+| Polygon | `usdt-polygon` `usdc-polygon` | `137` | 6 位小数 |
+| Base | `usdc-base` | `8453` | 6 位小数 |
+| Solana | `usdt-solana` `usdc-solana` | `900` | SPL；不支持原生 SOL |
+| Stellar | `usdc-stellar` | `1500` | 必须带 memo —— 会在充值信息块里给出 |
+| Bitcoin Lightning | `btc-lightning` | `lightning` | BOLT11；金额单位为聪 |
+
+原生 gas 币（SOL、BNB、ETH、MATIC）以及链上 BTC 均不接受。
+
+## 在你的 agent 里使用
+
+不管用哪个 agent，喂给它的东西都一样：上面那条命令，或者直接让它读
+[llms.txt](../llms.txt)。**用你自己的钱包付款永远不需要私钥。** 只有可选的
+`--send` 才会在本地签名，也只有它会读取 `ROZO_CHECKOUT_EVM_KEY` /
+`ROZO_CHECKOUT_SOL_KEY`。
+
+<details>
+<summary><b>Claude Code</b> —— 安装 skill，或者直接粘贴那条命令</summary>
+
+本仓库本身就是一个 Claude Code skill：它自带 `SKILL.md` 和 `scripts/dist/` 里的
+可执行文件。把它克隆到你的 skills 目录，Claude Code 会自动识别。
+
+```bash
+git clone https://github.com/RozoAI/rozo-checkout-skill ~/.claude/skills/rozo-checkout
+```
+
+或者跳过安装，直接让它执行：
+
+```
+用 Solana 上的 USDT 支付这个 OpenRouter 链接：
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+钱包：任意钱包，**无需私钥**。只有当你想让 Claude 用热钱包签名时才加 `--send`，
+那一步才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>Codex CLI</b> —— 写进 AGENTS.md，或者直接跑</summary>
+
+Codex 会读取项目根目录的 `AGENTS.md`。加一条常驻指令，它就不用每次都被告知怎么付：
+
+```
+要支付 OpenRouter / Coinbase 收款链接，执行：
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>OpenCode</b> —— 写进 AGENTS.md，或者直接跑</summary>
+
+OpenCode 同样读取项目根目录的 `AGENTS.md`，所以上面那段 Codex 的写法可以原样照搬。
+最短的路径依然是直接执行命令本身：
+
+```bash
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>Cline</b> —— 写进 .clinerules，或者直接跑</summary>
+
+Cline 从项目根目录的 `.clinerules` 读取常驻指令：
+
+```
+要支付 OpenRouter / Coinbase 收款链接，执行：
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>Cursor</b> —— 写进 .cursor/rules，或者直接跑</summary>
+
+在 `.cursor/rules/rozo-checkout.mdc` 加一条项目规则：
+
+```
+要支付 OpenRouter / Coinbase 收款链接，执行：
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>Hermes Agent</b> —— 在会话里跑那条命令</summary>
+
+Hermes Agent（Nous Research）有 shell 权限，也有自己的 skill 体系。用 `hermes`
+启动后这样说：
+
+```
+先抓取 https://checkout.rozo.ai/llms.txt，然后支付这个 OpenRouter 链接：
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>OpenClaw</b> —— openclaw agent exec</summary>
+
+OpenClaw 的无头入口用来跑一次性任务，很适合从脚本或聊天渠道里触发一笔付款：
+
+```bash
+openclaw agent exec "Pay this OpenRouter link with USDT on Solana by running: npx @rozoai/checkout pay <coinbase-link> --with usdt-solana"
+```
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>Pi</b> —— 在会话里跑那条命令</summary>
+
+Pi 是一个 BYOK 终端 agent，内置工具里就有 `bash`，可以直接执行命令。用 `pi`
+启动后这样说：
+
+```
+用 Solana 上的 USDT 支付这个 OpenRouter 链接，执行：
+npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
+```
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+<details>
+<summary><b>终端 —— 完全不用 agent</b> —— 一步步跑脚本</summary>
+
+每一步都自己来。打包产物是自包含的，除了 Node 18+ 之外不需要装任何东西。
+
+```bash
+git clone https://github.com/RozoAI/rozo-checkout-skill && cd rozo-checkout-skill
+LINK="https://payments.coinbase.com/payment-links/pl_01YOURLINKID"
+
+# 只读报价，不产生任何费用
+node scripts/dist/quote.js --url "$LINK"
+
+# 创建订单。此阶段完整充值地址会被扣留：你先拿到一份打码后的摘要用于核对。
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT
+
+# 决定付款之后，加 --confirm 重新执行同一条命令来释放它
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confirm
+
+# 用任意钱包按充值信息块付款，然后观察它结清
+node scripts/dist/status.js --rozo-payment-id <uuid> --watch
+```
+
+每个脚本在 stdout 上只打印一个 JSON 对象。退出码 `0` 表示成功，`1` 表示被拒绝/
+失败（读 `error.code`），`2` 表示用法错误，`3` 表示已提交但未确认。完整走一遍：
+[QUICKSTART](QUICKSTART.zh.md)。
+
+钱包：任意钱包，**无需私钥**。热钱包发送见 `send-evm.js` / `send-sol.js`，它们读取
+`ROZO_CHECKOUT_EVM_KEY` / `ROZO_CHECKOUT_SOL_KEY`。agent 和脚本必须显式传 `--with`：
+交互式选择只在终端里出现，而且刻意没有默认币种。
+</details>
+
+<details>
+<summary><b>任何其他 agent</b> —— 让它去读 llms.txt</summary>
+
+只要一个 agent 能抓 URL、能执行命令，它就能干这件事：
+
+```
+把 https://checkout.rozo.ai/llms.txt 抓进你的上下文，然后照着它
+支付这个 OpenRouter 链接：<coinbase-link>
+```
+
+如果 agent 没有 shell 但能发 HTTP 请求，它可以直接调用那四个公开端点 —— 见
+[工作原理](how-it-works.md)。
+
+钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+</details>
+
+## 三条必须知道的规则
+
+- **充值地址是一次性的。** 绝不要复用旧订单、缓存响应或截图里的地址。
+- **严格按显示的金额发送。** 它通常比账单金额大 —— 因为包含了跨桥费和网络费。
+- **绝不要对已入账的订单二次付款。** 一旦检测到已有付款，就停下来找人工核对；
+  再往一个一次性地址打第二笔钱，不保证能被记账。
+
+它拒绝去做哪些事、以及为什么，完整清单见
+[docs/safety.md](safety.md)。
+
+## 相关链接
+
+- [快速开始](QUICKSTART.zh.md) —— 五条命令，附预期输出
+- [工作原理](how-it-works.md) —— 流程、端点、标识符
+- [安全设计](safety.md) —— 每一道防线的细节
+- [SKILL.md](../SKILL.md) —— 面向 agent 的指令 · [llms.txt](../llms.txt) —— 单文件摘要
+- [checkout.rozo.ai/agent](https://checkout.rozo.ai/agent.html) —— 网页版，同样的东西
+- [Issues](https://github.com/RozoAI/rozo-checkout-skill/issues) —— bug 与需求
+
+## 更新日志
+
+- **0.1.1** —— 两条额度上限合并为一条：单笔付款不得超过 $1,100（按购买 $1,000
+  额度加 5% 手续费来设定），单会话累计上限与 `--yes-large` 绕过开关均已移除。文档
+  明确说明：用你自己的钱包付款不需要私钥，也不需要任何配置。
+- **0.1.0** —— 首个版本：`npx @rozoai/checkout`。
+
+## 许可证
+
+MIT。

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,74 @@
+# 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.** Keys come from the environment only
+  (`ROZO_CHECKOUT_EVM_KEY`, `ROZO_CHECKOUT_SOL_KEY`), are never printed and
+  never accepted on the command line; 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,19 @@ 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, and only that flag reads
+ROZO_CHECKOUT_EVM_KEY / ROZO_CHECKOUT_SOL_KEY (from the environment, never argv).
+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.
@@ -62,7 +70,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: