nodpay 0.2.34 → 0.2.36

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NodPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/SKILL.md

@@ -156,7 +156,7 @@ EOA wallets: replace passkey fields with `"humanSignerEoa": "0x..."`.
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| `--chain` | ✅ | `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `sepolia`, `base_sepolia` |
+| `--chain` | ✅ | `base`, `arbitrum`, `polygon`, `optimism`, `ethereum`, `sepolia`, `base_sepolia` |
 | `--safe` | ✅ | Wallet address |
 | `--to` | ✅ | Recipient |
 | `--value-eth` | ✅ | Amount in ETH |
@@ -165,7 +165,7 @@ EOA wallets: replace passkey fields with `"humanSignerEoa": "0x..."`.
 | `--recovery-signer` | first tx | Recovery signer address |
 | `--nonce` | **required** | Nonce for this proposal. Run `txs` first to determine. |
 
-Wallet address is the same across all chains. **Ask which chain if not specified.**
+Wallet address is the same across all chains. **Ask which chain if not specified.** Prefer L2 chains (Base, Arbitrum, etc.) — Ethereum mainnet gas is significantly more expensive.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodpay",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "NodPay CLI — propose on-chain payments from agent-human shared wallets",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
     "postpublish": "curl -s https://purge.jsdelivr.net/npm/nodpay@latest/SKILL.md > /dev/null && echo 'jsdelivr cache purged'"
   },
   "dependencies": {
-    "@nodpay/core": "^0.1.2",
+    "@nodpay/core": "^0.1.3",
     "@safe-global/relay-kit": "^4.1.1",
     "ethers": "^6.16.0"
   }

package/scripts/env.mjs

@@ -0,0 +1,59 @@
+/**
+ * Unified environment variable loader for NodPay CLI.
+ *
+ * Priority (highest wins):
+ *   1. process.env (real env — set by caller, SafeClaw injection, container, etc.)
+ *   2. ~/.nodpay/.env file (convenience layer for local dev)
+ *
+ * The .env file is loaded into process.env WITHOUT overriding existing values.
+ * This matches standard dotenv behavior and Unix conventions:
+ *   NODPAY_AGENT_KEY=0xabc npx nodpay propose  →  uses 0xabc, ignores file
+ *
+ * After loadDotEnv(), all code reads from process.env uniformly.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const HOME = process.env.HOME || process.env.USERPROFILE || '/tmp';
+const DEFAULT_ENV_PATH = join(HOME, '.nodpay', '.env');
+
+/**
+ * Parse a .env file and load values into process.env.
+ * Does NOT override existing env vars (real env takes priority).
+ *
+ * @param {string} [envPath] - Path to .env file. Defaults to ~/.nodpay/.env
+ */
+export function loadDotEnv(envPath = DEFAULT_ENV_PATH) {
+  if (!existsSync(envPath)) return;
+  try {
+    const lines = readFileSync(envPath, 'utf8').split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) continue;
+      const eqIdx = trimmed.indexOf('=');
+      const name = trimmed.slice(0, eqIdx).trim();
+      const value = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
+      // Only set if not already in process.env (real env wins)
+      if (!(name in process.env)) {
+        process.env[name] = value;
+      }
+    }
+  } catch {
+    // Non-fatal: .env file may not exist or be unreadable
+  }
+}
+
+/**
+ * Get an env var after .env has been loaded.
+ * Convenience wrapper — just reads process.env.
+ *
+ * @param {string} name - Environment variable name
+ * @param {string} [fallback] - Default value if not set
+ * @returns {string|undefined}
+ */
+export function env(name, fallback) {
+  return process.env[name] || fallback;
+}
+
+export { HOME, DEFAULT_ENV_PATH };

package/scripts/keygen.mjs

@@ -14,41 +14,32 @@
 import { Wallet } from 'ethers';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs';
 import { resolve, dirname, join } from 'path';
+import { loadDotEnv, env, HOME } from './env.mjs';
 
 const args = process.argv.slice(2);
 const envFileIdx = args.indexOf('--env-file');
-const HOME = process.env.HOME || process.env.USERPROFILE || '/tmp';
 const envFile = envFileIdx !== -1
   ? resolve(args[envFileIdx + 1])
   : join(HOME, '.nodpay', '.env');
 
 const ENV_VAR = 'NODPAY_AGENT_KEY';
 
-// Check if key already exists in the env file
-function findExistingKey() {
-  if (!existsSync(envFile)) return null;
-  const lines = readFileSync(envFile, '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() === ENV_VAR) {
-      const value = rest.join('=').trim().replace(/^["']|["']$/g, '');
-      if (value) return value;
-    }
-  }
-  return null;
-}
+// Load .env file into process.env (real env takes priority)
+loadDotEnv(envFile);
 
-const existing = findExistingKey();
+// Check if key already exists (process.env — from real env or .env file)
+const existing = env(ENV_VAR);
 
 if (existing) {
   try {
     const wallet = new Wallet(existing);
     console.log(wallet.address);
-    console.error(`${ENV_VAR} already configured in ${envFile}`);
+    const source = process.env[ENV_VAR] === existing && !existsSync(envFile)
+      ? 'environment variable'
+      : envFile;
+    console.error(`${ENV_VAR} already configured (${source})`);
   } catch {
-    console.error(`${ENV_VAR} exists in ${envFile} but is invalid. Remove it and re-run.`);
+    console.error(`${ENV_VAR} is set but invalid. Check your env or ${envFile}.`);
     process.exit(1);
   }
 } else {

package/scripts/propose.mjs

@@ -6,7 +6,7 @@
  * The agent signs first (1 of 2). The serialized SafeOperation is
  * output so the web app can have the user co-sign and submit.
  *
- * Agent key: read from .nodpay/.env (never from env vars or CLI args).
+ * Agent key: from process.env.NODPAY_AGENT_KEY (real env > ~/.nodpay/.env file > --remote-signer).
  * Chain config: resolved via --chain from @nodpay/core networks registry.
  * Bundler: NodPay public proxy (override with OP_STORE_URL for self-hosted).
  *
@@ -17,6 +17,7 @@
  *   --safe <address>         - Wallet (Safe) address
  *   --counterfactual         - Safe not yet deployed; include deployment in UserOp
  *   --human-signer-eoa <address>  - Human's EOA signer address (for EOA mode)
+ *   --remote-signer <url>    - SafeClaw proxy URL for remote signing (mutually exclusive with --human-signer-eoa)
  *   --salt <nonce>           - Salt nonce (required for counterfactual)
  *   --reuse-gas-from <shortHash>  - Reuse gas values from a previous op (shortHash prefix of safeOpHash)
  *   --nonce <n>              - Required. Use `txs` to find current nonce.
@@ -26,15 +27,22 @@
 
 import { Safe4337Pack } from '@safe-global/relay-kit';
 import { ethers } from 'ethers';
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { computeUserOpHash, ENTRYPOINT } from '@nodpay/core';
+import { loadDotEnv, env, HOME } from './env.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PENDING_DIR = join(__dirname, '..', '.pending-txs');
 mkdirSync(PENDING_DIR, { recursive: true });
 
+// Load ~/.nodpay/.env into process.env (real env takes priority, file is fallback)
+const _envFileArg = process.argv.includes('--env-file')
+  ? process.argv[process.argv.indexOf('--env-file') + 1]
+  : undefined;
+loadDotEnv(_envFileArg);
+
 // Resolve chain config: --chain flag auto-resolves from networks.json, env vars as fallback
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -63,57 +71,70 @@ if (chainArg) {
 }
 const ENTRYPOINT_ADDRESS = ENTRYPOINT;
 
-const HOME = process.env.HOME || process.env.USERPROFILE || '/tmp';
+// SECURITY: Agent key is read from process.env.NODPAY_AGENT_KEY.
+// The .env file was loaded above (loadDotEnv) without overriding real env vars.
+// Priority: real env (SafeClaw injection, container, explicit) > .env file.
+// The key never appears in stdout or agent conversation history.
 
-// SECURITY: Read agent key from ~/.nodpay/.env file (chmod 600), not from
-// process.env or CLI args. The key is loaded at runtime by the script itself,
-// so it never passes through the LLM agent's context or conversation history.
-function loadAgentKey() {
-  try {
-    const envPath = join(HOME, '.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 = null; // always use --safe flag
 
 // BUNDLER: NodPay provides a public bundler proxy at nodpay.ai/api/bundler so
 // agents don't need their own bundler API key. This is a thin relay — it
 // forwards the UserOp to a bundler service and returns the result. The proxy
 // only sees the already-signed (partial) UserOp; it cannot modify or execute it.
-// Optional overrides (OP_STORE_URL, WEB_APP_URL) also read from ~/.nodpay/.env.
-function loadDotEnvVar(name, fallback) {
-  try {
-    const envPath = join(HOME, '.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 [k, ...rest] = trimmed.split('=');
-      if (k.trim() === name) return rest.join('=').trim().replace(/^["']|["']$/g, '');
-    }
-  } catch {}
-  return fallback;
-}
-const opStoreBase = loadDotEnvVar('OP_STORE_URL', 'https://nodpay.ai/api');
+const opStoreBase = env('OP_STORE_URL', 'https://nodpay.ai/api');
 const BUNDLER_URL = `${opStoreBase}/bundler/${CHAIN_ID}`;
 
-if (!NODPAY_AGENT_KEY) {
-  console.error(JSON.stringify({ error: 'Missing NODPAY_AGENT_KEY in ~/.nodpay/.env — run npx nodpay keygen first' }));
-  process.exit(1);
-}
+// --- Agent key: remote signer (SafeClaw proxy) or local key (~/.nodpay/.env) ---
+const _remoteSignerUrl = process.argv.includes('--remote-signer')
+  ? process.argv[process.argv.indexOf('--remote-signer') + 1]
+  : undefined;
+
+let AGENT_ADDRESS;
+let signHash;
+let _localAgentKey; // only set in local mode, used for SDK init (EOA signer)
+
+if (_remoteSignerUrl) {
+  // Remote signer mode: get address + signing from SafeClaw proxy
+  const addrRes = await fetch(`${_remoteSignerUrl}/address`);
+  if (!addrRes.ok) {
+    const err = await addrRes.json().catch(() => ({}));
+    console.error(JSON.stringify({
+      error: err.error || 'Failed to get agent address from remote signer',
+      code: err.code || 'REMOTE_SIGNER_ERROR'
+    }));
+    process.exit(1);
+  }
+  AGENT_ADDRESS = (await addrRes.json()).address;
+
+  signHash = async (hash) => {
+    const signRes = await fetch(`${_remoteSignerUrl}/sign/${AGENT_ADDRESS}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ hash })
+    });
+    if (!signRes.ok) {
+      const err = await signRes.json().catch(() => ({}));
+      throw new Error(err.error || 'Remote signing failed');
+    }
+    return (await signRes.json()).signature;
+  };
+} else {
+  // Local mode: read key from process.env (loaded from real env or ~/.nodpay/.env)
+  const NODPAY_AGENT_KEY = env('NODPAY_AGENT_KEY');
+  if (!NODPAY_AGENT_KEY) {
+    console.error(JSON.stringify({ error: 'Missing NODPAY_AGENT_KEY — set env var, add to ~/.nodpay/.env, or use --remote-signer' }));
+    process.exit(1);
+  }
+  _localAgentKey = NODPAY_AGENT_KEY;
+  const agentWallet = new ethers.Wallet(NODPAY_AGENT_KEY);
+  AGENT_ADDRESS = agentWallet.address;
 
-const agentWallet = new ethers.Wallet(NODPAY_AGENT_KEY);
-const AGENT_ADDRESS = agentWallet.address;
+  signHash = async (hash) => {
+    const sig = agentWallet.signingKey.sign(hash);
+    return ethers.Signature.from(sig).serialized;
+  };
+}
 
 const args = process.argv.slice(2);
 function getArg(name) {
@@ -139,6 +160,12 @@ const passkeyVerifier = getArg('--passkey-verifier') || '0x445a0683e494ea0c5AF3E
 const recoverySigner = getArg('--recovery-signer');
 const isPasskey = !!(passkeyX && passkeyY);
 
+// Phase 1: --remote-signer + --human-signer-eoa is not supported
+if (_remoteSignerUrl && humanSigner) {
+  console.error(JSON.stringify({ error: '--remote-signer and --human-signer-eoa cannot be combined. Remote signer mode only supports passkey wallets.' }));
+  process.exit(1);
+}
+
 if (!to) {
   console.error(JSON.stringify({ error: 'Missing --to <address>' }));
   process.exit(1);
@@ -151,6 +178,18 @@ if (!ethers.isAddress(to)) {
 
 const SAFE_ADDRESS = safeOverride || DEFAULT_SAFE;
 
+// Read optional wallet JSON for rpId (SafeClaw cross-origin passkey support)
+let walletRpId = null;
+if (SAFE_ADDRESS) {
+  const walletJsonPath = join(HOME, '.nodpay', 'wallets', `${SAFE_ADDRESS}.json`);
+  if (existsSync(walletJsonPath)) {
+    try {
+      const walletData = JSON.parse(readFileSync(walletJsonPath, 'utf8'));
+      if (walletData.rpId) walletRpId = walletData.rpId;
+    } catch {}
+  }
+}
+
 if (!isCounterfactual && !SAFE_ADDRESS) {
   console.error(JSON.stringify({ error: 'Missing SAFE_ADDRESS. Use --safe <address> or set SAFE_ADDRESS env, or use --counterfactual.' }));
   process.exit(1);
@@ -290,8 +329,8 @@ try {
       initOptions.options = { safeAddress: SAFE_ADDRESS };
     }
   } else {
-    // EOA signer: agent key as primary signer
-    initOptions.signer = NODPAY_AGENT_KEY;
+    // EOA signer: agent key as primary signer (requires local key)
+    initOptions.signer = _localAgentKey;
     if (isCounterfactual) {
       // Canonical owner order: [humanSigner, agentSigner, recoverySigner] — must match frontend
       const eoaOwners = recoverySigner
@@ -448,11 +487,8 @@ try {
     verifyingContract: safeOperation.options.moduleAddress,
   };
 
-  // Always sign manually with the agent's private key over the canonical hash
-  // (Using SDK's signSafeOperation would apply viem hex transforms that produce
-  //  a different hash than getHash(), making server-side verification impossible)
-  const sig = agentWallet.signingKey.sign(safeOpHash);
-  const agentSig = ethers.Signature.from(sig).serialized;
+  // Sign with agent key: local wallet or remote signer (SafeClaw proxy)
+  const agentSig = await signHash(safeOpHash);
   safeOperation.addSignature({
     signer: AGENT_ADDRESS,
     data: agentSig,
@@ -515,6 +551,10 @@ try {
     agent: AGENT_ADDRESS,
     agentSignature: safeOperationJson.signatures,
     createdAt: new Date().toISOString(),
+    // SafeClaw integration: passkey coordinates + recovery for approve page fallback
+    passkeyX: passkeyX || null,
+    passkeyY: passkeyY || null,
+    recoveryAddress: recoverySigner || null,
   };
 
   // Extract raw agent signature for server auth
@@ -537,8 +577,14 @@ try {
       result.opStoreError = storeData.error || `HTTP ${storeRes.status}`;
     }
     if (storeData.shortHash) {
-      const webBase = loadDotEnvVar('WEB_APP_URL', 'https://nodpay.ai/');
-      approveUrl = `${webBase}approve?safeOpHash=${storeData.safeOpHash}`;
+      const webBase = env('WEB_APP_URL', 'https://nodpay.ai/');
+      // Build approve URL with passkey params for SafeClaw users (no localStorage)
+      const approveParams = new URLSearchParams({ safeOpHash: storeData.safeOpHash });
+      if (passkeyX) approveParams.set('px', passkeyX);
+      if (passkeyY) approveParams.set('py', passkeyY);
+      if (recoverySigner) approveParams.set('recovery', recoverySigner);
+      if (walletRpId) approveParams.set('rpId', walletRpId);
+      approveUrl = `${webBase}approve?${approveParams.toString()}`;
       result.approveUrl = approveUrl;
       result.opStoreSafeOpHash = storeData.safeOpHash;
       result.opStoreShortHash = storeData.shortHash;