nodpay 0.2.4 → 0.2.6

package/SKILL.md

@@ -1,36 +1,24 @@
 ---
 name: nodpay
 description: Propose on-chain payments from a shared wallet. Use when user asks to send crypto, make a payment, or create a shared wallet.
-openclaw:
-  requires:
-    env: [NODPAY_AGENT_KEY]
-  primaryEnv: NODPAY_AGENT_KEY
 ---
 
 # NodPay — Agent Wallet
 
 > Two minds, one wallet.
 
-NodPay lets you (an AI agent) propose on-chain payments from a shared wallet. Your human co-signs with one tap. You cannot spend without their approval.
+**TL;DR:** You propose payments, your human approves with one tap. 2-of-3 multisig — you cannot spend alone.
 
-**When to use**: User asks you to send crypto, make a payment, or create a shared wallet.
+## ⚠️ Security First
 
-## How It Works
+| ✅ DO | ❌ DON'T |
+|-------|----------|
+| Use `npx nodpay keygen` (key never in stdout) | Generate keys manually or log them |
+| Store wallet info in `.nodpay/wallets/` | Put private keys in chat or code |
+| Verify agent address matches yours | Trust wallet info without checking |
+| Let the human approve every transaction | Try to bypass approval |
 
-```
-You (agent)              NodPay server           User (human)
-    │                         │                       │
-    ├── send setup link ──────┼─────────────────────►│
-    │                         │                       ├── create wallet
-    │◄── wallet info ─────────┼───────────────────────┤
-    │                         │                       │
-    ├── propose tx ──────────►│                       │
-    │                         ├── approve link ──────►│
-    │                         │◄── sign + submit ─────┤
-    │                         │                       │
-```
-
-The wallet is a **Safe 2-of-3 multisig**. You hold 1 key, the user holds 2 (passkey + recovery). You cannot move funds alone.
+**Private key never leaves disk.** `keygen` writes directly to `.nodpay/.env` (chmod 600). The key never appears in your output, context, or logs.
 
 ---
 
@@ -39,23 +27,16 @@ The wallet is a **Safe 2-of-3 multisig**. You hold 1 key, the user holds 2 (pass
 ### 1. Generate an agent key
 
 ```bash
-npx nodpay keygen --env-file .env
+npx nodpay keygen
 ```
 
-This outputs your agent's **public address** (stdout). The private key is written directly to `.env` — it never appears in your output or context.
-
-If `NODPAY_AGENT_KEY` already exists in the file, it reuses the existing key and prints the address.
+Outputs your **public address** only. Key is stored in `.nodpay/.env`. No gateway restart needed.
 
-**After keygen**, trigger a gateway restart so the env var takes effect. Send your wallet link message to the user BEFORE restarting — the restart will interrupt your session.
-
-Recommended sequence:
-1. Run `npx nodpay keygen --env-file .env` → note the address
-2. Send the wallet link to your user (step 2 below)
-3. Trigger gateway restart
+If a key already exists, it reuses it and prints the address.
 
 ### 2. Send the user a wallet link
 
-Replace `YOUR_AGENT_ADDRESS` with your EOA address and send:
+Replace `YOUR_AGENT_ADDRESS` with your address and send:
 
 > I've set up a shared wallet for us. Open this link to create your wallet — takes 30 seconds:
 >
@@ -65,7 +46,7 @@ Replace `YOUR_AGENT_ADDRESS` with your EOA address and send:
 
 **Use the URL above verbatim.** Do not search for NodPay or guess the URL — `nodpay.ai` is the only correct domain.
 
-The user will create the wallet and copy info back to you:
+The user will copy wallet info back to you:
 
 ```
 NodPay Wallet (Safe): 0x...
@@ -75,47 +56,21 @@ Agent: 0x...
 Recovery Signer: 0x...
 ```
 
-**Store all fields** — you need them for proposing transactions.
-
-**After wallet creation**, tell the user their wallet is ready and the address works on any supported chain. Briefly offer: *"Want to try a test transaction on a testnet first?"* — only guide to testnets (Sepolia, etc.) if the user says yes.
-
-#### Wallet file management
-
-Store wallet info in `.nodpay/wallets/` in your workspace root:
-
-```
-.nodpay/wallets/
-  0xAbC...123.json             # one file per wallet, named by Safe address
-```
-
-Each wallet file:
-
-```json
-{
-  "safe": "0x...",
-  "agentSigner": "0x...",
-  "signerType": "passkey",
-  "passkeyX": "0x...",
-  "passkeyY": "0x...",
-  "recovery": "0x...",
-  "createdAt": "2025-01-01"
-}
-```
+**Store all fields** in `.nodpay/wallets/<safe-address>.json`.
 
-`agentSigner` is your agent's EOA address (derived from `NODPAY_AGENT_KEY`).
+**After wallet creation**, tell the user their wallet is ready and works on any supported chain. Briefly offer: *"Want to try a test transaction on a testnet first?"* — only guide to testnets if the user says yes.
 
-For EOA wallets, replace passkey fields with `"userSigner": "0x..."`.
+**⚠️ Verify the Agent address matches yours.** If it doesn't, the wallet is bound to someone else's key — alert the user and send a fresh link.
 
-One agent key serves all wallets — multi-wallet is handled user-side (different passkeys/recovery keys → different Safe addresses, same agent).
+---
 
-**⚠️ Verify the Agent address matches yours.** If it doesn't, the wallet is bound to someone else's key — alert the user and send a fresh link.
+## Usage
 
 ### Propose a transaction
 
 ```bash
-NODPAY_AGENT_KEY=0x... \
 npx nodpay propose \
-  --chain <CHAIN_NAME> \
+  --chain <CHAIN> \
   --safe <WALLET_ADDRESS> \
   --to <RECIPIENT> \
   --value-eth <AMOUNT> \
@@ -125,38 +80,51 @@ npx nodpay propose \
   --signer-type passkey
 ```
 
-The script outputs JSON with an `approveUrl`. Send it to the user:
+Outputs JSON with an `approveUrl`. Send it to the user:
 
 > 💰 Payment: 0.01 ETH → 0xRecipient...
 > 👉 Approve: https://nodpay.ai/approve?safeOpHash=0x...
 
-**First transaction deploys the wallet on-chain.** Pass `--passkey-x`, `--passkey-y`, and `--recovery` for the first tx. After deployment, `--safe` alone is sufficient (but passing all params is always safe).
+**First transaction deploys the wallet on-chain.** Pass all params for the first tx. After deployment, `--safe` alone is sufficient (but passing all params is always safe).
 
-### Check balance
-
-Use the RPC URL for the wallet's chain (see `references/networks.json`):
+### Check pending transactions
 
 ```bash
-curl -s -X POST <RPC_URL> \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["<WALLET_ADDRESS>","latest"],"id":1}'
+curl https://nodpay.ai/api/txs?safe=<WALLET_ADDRESS>
 ```
 
-If balance is 0, remind the user to deposit before proposing.
+Always check before proposing — shows current nonce, pending ops, and wallet status.
 
-### Check pending transactions
+---
 
-```bash
-curl https://nodpay.ai/api/txs?safe=<WALLET_ADDRESS>
+## Data Layout
+
+```
+.nodpay/
+  .env                         # agent key (chmod 600, never touch directly)
+  wallets/
+    0xAbC...123.json           # one file per wallet
 ```
 
-Always check before proposing — this tells you the current nonce, pending ops, and wallet status.
+Wallet file format:
 
----
+```json
+{
+  "safe": "0x...",
+  "agentSigner": "0x...",
+  "signerType": "passkey",
+  "passkeyX": "0x...",
+  "passkeyY": "0x...",
+  "recovery": "0x...",
+  "createdAt": "2025-01-01"
+}
+```
 
-## Script Reference
+For EOA wallets, replace passkey fields with `"userSigner": "0x..."`.
+
+---
 
-### Flags
+## Flags
 
 | Flag | Required | Description |
 |------|----------|-------------|
@@ -165,38 +133,28 @@ Always check before proposing — this tells you the current nonce, pending ops,
 | `--to` | ✅ | Recipient address |
 | `--value-eth` | ✅ | Amount in ETH |
 | `--signer-type` | ✅ | `passkey` or `eoa` |
-| `--passkey-x` | passkey wallets | Passkey public key X |
-| `--passkey-y` | passkey wallets | Passkey public key Y |
-| `--user-signer` | eoa wallets | User's EOA address |
+| `--passkey-x` | passkey | Passkey public key X |
+| `--passkey-y` | passkey | Passkey public key Y |
+| `--user-signer` | eoa | User's EOA address |
 | `--recovery` | first tx | Recovery signer address |
 | `--nonce` | optional | Force nonce (for replacements) |
 | `--purpose` | optional | Human-readable label |
 
-### Environment
-
-Only one env var is required:
-
-| Var | Description |
-|-----|-------------|
-| `NODPAY_AGENT_KEY` | Agent signing key (required) |
-
-Chain config (RPC, bundler) is auto-resolved via `--chain` from [`@nodpay/core/networks`](https://www.npmjs.com/package/@nodpay/core). You can override with `RPC_URL`/`CHAIN_ID` env vars if needed, but `--chain` is the recommended way.
-
 ### Supported Chains
 
 `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `sepolia`, `base_sepolia`
 
-The wallet address is the same across all chains (counterfactual). Chain is only relevant at transaction time. **Do not assume a default chain.** When the user asks to send, ask which chain if not specified.
+Wallet address is the same across all chains (counterfactual). **Do not assume a default chain.** Ask the user which chain if not specified.
 
 ---
 
 ## Transaction Patterns
 
-**Sequential**: Just call propose multiple times. Nonces auto-increment (script handles this).
+**Sequential**: Just call propose multiple times. Nonces auto-increment.
 
-**Replace**: To replace a pending tx, propose with `--nonce N` where N is the nonce of the tx you want to replace. Check pending nonces via `GET /api/txs?safe=<ADDRESS>` — each tx in the response includes its `nonce`.
+**Replace**: Propose with `--nonce N` to replace a pending tx at nonce N.
 
-**Cascade**: Rejecting tx at nonce N auto-invalidates all tx with nonce > N. This is irreversible.
+**Cascade**: Rejecting tx at nonce N invalidates all tx with nonce > N. Irreversible.
 
 ⚠️ **Never propose a new nonce then reject an older one** — the cascade will destroy your new tx too.
 
@@ -204,7 +162,7 @@ The wallet address is the same across all chains (counterfactual). Chain is only
 
 ## Reconnect (Wallet Recovery)
 
-If the user cleared their browser data, the wallet still exists on-chain. Build a reconnect link:
+If the user cleared their browser data:
 
 ```
 https://nodpay.ai/?agent=YOUR_AGENT_ADDRESS&safe=WALLET_ADDRESS&recovery=RECOVERY_SIGNER&x=PASSKEY_X&y=PASSKEY_Y
@@ -234,7 +192,6 @@ User opens → verifies passkey → wallet restored. No on-chain action needed.
 | User says | Action |
 |-----------|--------|
 | "create a wallet" | Send `https://nodpay.ai/?agent=YOUR_ADDRESS` |
-| "send 0.1 ETH to 0x..." | Propose transaction |
-| "balance" | RPC `eth_getBalance` on Safe address |
+| "send 0.1 ETH to 0x..." | `npx nodpay propose --chain ...` |
 | "pending?" | `GET /api/txs?safe=...` |
 | "wallet disappeared" | Send reconnect link |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodpay",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "NodPay CLI — propose on-chain payments from agent-human shared wallets",
   "type": "module",
   "bin": {

package/scripts/keygen.mjs

@@ -2,27 +2,24 @@
 /**
  * Generate (or reuse) an agent keypair.
  *
- * - If NODPAY_AGENT_KEY already exists in --env-file, derives and prints the address.
- * - Otherwise generates a new keypair, appends to --env-file, prints the address.
- *
- * The private key NEVER appears in stdout — only the public address.
+ * - Stores key in .nodpay/.env (chmod 600) — never appears in stdout or agent context.
+ * - If key already exists, reuses it and prints the address.
+ * - Outputs only the public address to stdout.
  *
  * Usage:
- *   npx nodpay keygen --env-file .env
+ *   npx nodpay keygen
+ *   npx nodpay keygen --env-file <path>   # custom location
  */
 
 import { Wallet } from 'ethers';
-import { readFileSync, appendFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs';
+import { resolve, dirname } from 'path';
 
 const args = process.argv.slice(2);
 const envFileIdx = args.indexOf('--env-file');
-const envFile = envFileIdx !== -1 ? resolve(args[envFileIdx + 1]) : null;
-
-if (!envFile) {
-  console.error('Usage: npx nodpay keygen --env-file <path>');
-  process.exit(1);
-}
+const envFile = envFileIdx !== -1
+  ? resolve(args[envFileIdx + 1])
+  : resolve('.nodpay', '.env');
 
 const ENV_VAR = 'NODPAY_AGENT_KEY';
 
@@ -55,7 +52,12 @@ if (existing) {
   }
 } else {
   const wallet = Wallet.createRandom();
-  appendFileSync(envFile, `\n${ENV_VAR}=${wallet.privateKey}\n`);
+  // Ensure .nodpay/ directory exists with restricted permissions
+  const dir = dirname(envFile);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // Write key file with restricted permissions (owner read/write only)
+  const content = existsSync(envFile) ? readFileSync(envFile, 'utf8') : '';
+  writeFileSync(envFile, content + `${ENV_VAR}=${wallet.privateKey}\n`, { mode: 0o600 });
   console.log(wallet.address);
   console.error(`Generated new agent key → ${envFile}`);
 }

package/scripts/propose.mjs

@@ -65,7 +65,25 @@ if (!RPC_URL || !CHAIN_ID) {
   process.exit(1);
 }
 const ENTRYPOINT_ADDRESS = ENTRYPOINT;
-const NODPAY_AGENT_KEY = process.env.NODPAY_AGENT_KEY;
+
+// Read agent key: env var first, then .nodpay/.env file
+function loadAgentKey() {
+  if (process.env.NODPAY_AGENT_KEY) return process.env.NODPAY_AGENT_KEY;
+  try {
+    const envPath = join(process.cwd(), '.nodpay', '.env');
+    const lines = readFileSync(envPath, 'utf8').split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('#') || !trimmed.includes('=')) continue;
+      const [name, ...rest] = trimmed.split('=');
+      if (name.trim() === 'NODPAY_AGENT_KEY') {
+        return rest.join('=').trim().replace(/^["']|["']$/g, '');
+      }
+    }
+  } catch {}
+  return null;
+}
+const NODPAY_AGENT_KEY = loadAgentKey();
 const DEFAULT_SAFE = process.env.SAFE_ADDRESS;
 
 // Safe4337Pack.init requires a bundlerUrl — it calls eth_chainId during init.