clanker-wallet 0.3.0 → 0.4.0

package/README.md

@@ -17,8 +17,9 @@ bunx clanker-wallet
 ## Quick Start
 
 ```bash
-# 1. Human goes to https://clanker-wallet.xyz, connects wallet, copies pairing JSON
-# 2. Pair (one-time)
+# 1. Human goes to https://clanker-wallet.xyz, connects wallet, clicks "copy prompt for agent",
+#    pastes the prompt to you. The prompt contains a JSON pairing code.
+# 2. Pair (one-time) — extract the JSON from the prompt
 clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
 
 # 3. Send a transaction (blocks until human approves or rejects)
@@ -80,11 +81,11 @@ clanker-wallet status
 
 ### `whoami`
 
-Show agent identity.
+Show agent identity. `fingerprint` (first 16 hex chars of the public key) is what the web app shows for this agent; the human compares it before trusting the agent.
 
 ```bash
 clanker-wallet whoami
-# → {"agent_id":"agent_abc123","public_key":"ab12cd..."}
+# → {"agent_id":"agent_abc123","public_key":"ab12cd34ef567890...","fingerprint":"ab12 cd34 ef56 7890"}
 ```
 
 ## Exit Codes
@@ -165,13 +166,13 @@ tx_hash = await agent.request_tx(RequestTxOptions(
 
 ## How It Works
 
-1. Human opens [clanker-wallet.xyz](https://clanker-wallet.xyz), connects wallet, gets a pairing code
-2. Agent runs `clanker-wallet pair` — establishes E2E encrypted channel
+1. Human opens [clanker-wallet.xyz](https://clanker-wallet.xyz), connects wallet, clicks "copy prompt for agent" — gets a paste-ready prompt that bundles intent, the setup guide URL, and the pairing JSON
+2. Human pastes the prompt to their AI agent. Agent extracts the JSON and runs `clanker-wallet pair` — establishes E2E encrypted channel
 3. Agent runs `clanker-wallet tx` — encrypts tx with nacl.box, sends via WebSocket relay
-4. Human reviews tx details, simulation, risk flags in the web app
+4. Human reviews tx details, simulation, risk flags in the web app. A new agent shows up as unverified with its fingerprint; auto-approve rules only apply after the human trusts it. Contract rules (address + methods) don't limit token amounts or recipients
 5. Human approves → wallet signs + broadcasts → agent gets the tx hash
 
-All messages are encrypted end-to-end. The relay server never sees plaintext.
+Request and response payloads are encrypted end-to-end; the relay only forwards them. Exception: when paired in managed mode, the agent also sends the transaction fields (from, to, value, data, chainId) to the relay for simulation.
 
 ## License
 

package/SKILL.md

@@ -18,22 +18,27 @@ Or use without installing: `npx clanker-wallet` / `bunx clanker-wallet`
 
 ## Pairing (one-time)
 
-Before you can send transactions, you must pair with the human. Ask them:
+The human will paste a prompt block from https://clanker-wallet.xyz that looks like this:
 
-> "I need to send blockchain transactions on your behalf. Please go to https://clanker-wallet.xyz, connect your wallet, and give me the pairing JSON."
+> read the setup guide first: https://clanker-wallet.xyz/llms.txt
+>
+> then pair using this code:
+> `{"version":1,"pubkey":"ab12cd...","relay":"wss://...","wallet":"0x..."}`
 
-The human will give you a JSON string like:
-```json
-{"version":1,"pubkey":"ab12cd...","relay":"wss://clanker-wallet-relay-625052130878.us-east1.run.app/ws","wallet":"0x..."}
-```
+Extract the JSON object (the line starting with `{`) and pair:
 
-Pair with it:
 ```bash
 clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
 ```
 
+If the human only pastes raw JSON (no prompt prose), pair with it directly. If they only paste the URL, ask them to click "copy prompt for agent" on the pairing screen.
+
 This saves identity and pairing to `~/.clanker-wallet/`. You only need to do this once.
 
+### Trust (first request)
+
+The web app lists a new agent as unverified and shows its fingerprint (e.g. `ab12 cd34 ef56 7890`). Until the human compares it with the `fingerprint` from `clanker-wallet whoami` and clicks "trust this agent", none of their auto-approve rules apply: every tx waits for manual approval. Contract rules (contract address + allowed methods) do not limit token amounts or recipients: a rule allowing `transfer` on a token auto-approves any amount to any recipient. If asked, run `clanker-wallet whoami` and share the fingerprint.
+
 ### Transaction notifications
 
 After pairing, ask the human:
@@ -136,7 +141,7 @@ clanker-wallet status
 
 # Show agent identity
 clanker-wallet whoami
-# → {"agent_id":"agent_abc123","public_key":"ab12cd..."}
+# → {"agent_id":"agent_abc123","public_key":"ab12cd34ef567890...","fingerprint":"ab12 cd34 ef56 7890"}
 ```
 
 ## Troubleshooting

package/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { ClankerWallet } from '../dist/index.js'
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs'
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs'
 import { join } from 'path'
 import { homedir } from 'os'
 
@@ -14,6 +14,8 @@ const EXIT = { OK: 0, REJECTED: 1, TIMEOUT: 2, CONNECTION: 3, NOT_PAIRED: 4, BAD
 // ── helpers ──────────────────────────────────────────────────────────
 const hex = (bytes) => Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')
 const fromHexStr = (h) => new Uint8Array(h.match(/.{2}/g).map(b => parseInt(b, 16)))
+/** short id the human compares in the web app: first 16 hex (64 bits) of the x25519 pubkey, "ab12 cd34 ef56 7890" */
+const fingerprint = (pubkeyHex) => pubkeyHex.slice(0, 16).toLowerCase().match(/.{1,4}/g).join(' ')
 
 function die(msg, code) {
   process.stderr.write(msg + '\n')
@@ -24,19 +26,25 @@ function out(obj) {
   process.stdout.write(JSON.stringify(obj) + '\n')
 }
 
+// owner-only; an existing dir from an older version is tightened too
 function ensureDir() {
-  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true })
+  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 })
+  else chmodSync(STATE_DIR, 0o700)
 }
 
+// identity.json holds the agent secret key: owner-only, tightened if an older version left it readable
 function loadIdentity() {
   if (!existsSync(IDENTITY_FILE)) return null
+  ensureDir()
+  chmodSync(IDENTITY_FILE, 0o600)
   try { return JSON.parse(readFileSync(IDENTITY_FILE, 'utf8')) }
   catch { return null }
 }
 
 function saveIdentity(data) {
   ensureDir()
-  writeFileSync(IDENTITY_FILE, JSON.stringify(data, null, 2) + '\n')
+  writeFileSync(IDENTITY_FILE, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
+  chmodSync(IDENTITY_FILE, 0o600)
 }
 
 function loadPairing() {
@@ -145,6 +153,7 @@ async function cmdTx(flags) {
     pubkey: pairing.pubkey,
     relay: pairing.relay,
     wallet: pairing.wallet,
+    mode: pairing.mode || undefined,
   })
   wallet.pair(pairingJson)
 
@@ -189,6 +198,7 @@ function cmdWhoami() {
   out({
     agent_id: wallet.agentId,
     public_key: hex(wallet.publicKey),
+    fingerprint: fingerprint(hex(wallet.publicKey)),
   })
 }
 

package/dist/client.js

@@ -43,6 +43,7 @@ export class ClankerWallet extends TypedEmitter {
             humanPubkeyHex: data.pubkey,
             relayUrl: data.relay,
             humanWallet: data.wallet || null,
+            mode: data.mode || 'encrypted',
         };
         this.emit('paired', { relay: data.relay, wallet: data.wallet || '' });
         return data;
@@ -56,7 +57,7 @@ export class ClankerWallet extends TypedEmitter {
         if (!this.pairing) {
             throw new Error('not paired — call pair() first');
         }
-        const { humanPubkey, humanPubkeyHex, relayUrl } = this.pairing;
+        const { humanPubkey, humanPubkeyHex, relayUrl, humanWallet, mode } = this.pairing;
         const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
         const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
         const txRequest = {
@@ -130,18 +131,32 @@ export class ClankerWallet extends TypedEmitter {
                         ciphertext,
                         signing_pubkey: this.signingPubkeyHex,
                     };
-                    ws.send(JSON.stringify({
+                    const wsMsg = {
                         type: 'message',
                         room: humanPubkeyHex,
                         payload: JSON.stringify(envelope),
-                    }));
+                    };
+                    // managed mode: relay gets plaintext tx params so it can simulate
+                    if (mode === 'managed') {
+                        wsMsg.simulate = {
+                            from: humanWallet || '',
+                            to: options.transaction.to,
+                            value: options.transaction.value,
+                            data: options.transaction.data,
+                            chainId: options.chain_id,
+                        };
+                    }
+                    ws.send(JSON.stringify(wsMsg));
                     this.emit('request_sent', { request_id: requestId });
                     return;
                 }
                 if (msg.type === 'message') {
                     try {
                         const envelope = JSON.parse(msg.payload);
-                        const plaintext = decryptMessage(envelope.ciphertext, fromHex(envelope.sender_pubkey), this.secretKey);
+                        // only the paired human may answer
+                        if (envelope.sender_pubkey?.toLowerCase() !== humanPubkeyHex.toLowerCase())
+                            return;
+                        const plaintext = decryptMessage(envelope.ciphertext, humanPubkey, this.secretKey);
                         if (!plaintext)
                             return;
                         const response = JSON.parse(plaintext);

package/dist/crypto.js

@@ -20,7 +20,13 @@ export function encryptMessage(message, recipientPublicKey, senderSecretKey) {
 }
 /** decrypt a nacl.box message. payload = base64(nonce + ciphertext). */
 export function decryptMessage(base64Payload, senderPublicKey, recipientSecretKey) {
-    const raw = base64ToBytes(base64Payload);
+    let raw;
+    try {
+        raw = base64ToBytes(base64Payload);
+    }
+    catch {
+        return null;
+    }
     if (raw.length <= nacl.box.nonceLength)
         return null;
     const nonce = raw.slice(0, nacl.box.nonceLength);
@@ -38,7 +44,13 @@ export function toHex(bytes) {
 }
 /** hex string → Uint8Array (strips 0x prefix if present) */
 export function fromHex(hex) {
-    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const clean = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0) {
+        throw new Error('invalid hex string: length must be even');
+    }
+    if (!/^[0-9a-fA-F]*$/.test(clean)) {
+        throw new Error('invalid hex string: contains non-hex characters');
+    }
     const bytes = new Uint8Array(clean.length / 2);
     for (let i = 0; i < bytes.length; i++) {
         bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
@@ -47,7 +59,11 @@ export function fromHex(hex) {
 }
 /** derive an Ed25519 signing keypair from a 32-byte seed */
 export function signingKeypairFromSeed(seed) {
-    return nacl.sign.keyPair.fromSeed(seed);
+    if (seed.length !== nacl.sign.seedLength) {
+        throw new Error(`invalid seed length: expected ${nacl.sign.seedLength} bytes, got ${seed.length}`);
+    }
+    // copy to keep derivation independent of caller-owned mutable buffers
+    return nacl.sign.keyPair.fromSeed(new Uint8Array(seed));
 }
 /** sign a message string with an Ed25519 secret key. returns base64(signature). */
 export function signMessage(message, signingSecretKey) {

package/dist/types.d.ts

@@ -40,6 +40,8 @@ export interface PairingData {
     pubkey: string;
     relay: string;
     wallet: string;
+    /** "encrypted" (default): relay sees only ciphertext. "managed": relay also receives tx params for simulation. */
+    mode?: 'encrypted' | 'managed';
 }
 /** options for requestTx */
 export interface RequestTxOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,13 @@
   "bin": {
     "clanker-wallet": "bin/cli.js"
   },
-  "files": ["dist", "bin", "SKILL.md", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "bin",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
   "license": "MIT",
   "author": "Clanker Wallet Contributors",
   "repository": {
@@ -21,7 +27,27 @@
     "url": "git+https://github.com/almogdepaz/clanker-wallet.git"
   },
   "homepage": "https://github.com/almogdepaz/clanker-wallet#readme",
-  "keywords": ["wallet", "ai-agent", "ethereum", "e2e-encrypted", "transaction-approval"],
+  "keywords": [
+    "wallet",
+    "ai-agent",
+    "ethereum",
+    "e2e-encrypted",
+    "transaction-approval",
+    "blockchain",
+    "web3",
+    "langchain",
+    "human-in-the-loop",
+    "evm",
+    "agent-wallet",
+    "llm",
+    "typescript",
+    "base",
+    "polygon",
+    "transaction",
+    "approval",
+    "defi",
+    "vercel-ai-sdk"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",