@toon-protocol/client-mcp 0.31.0 → 0.31.2

package/README.md

@@ -56,16 +56,43 @@ The `toon-client` MCP server exposes **8 tools**:
 ## Install
 
 ```bash
-pnpm add -g @toon-protocol/client-mcp     # or use npx/pnpm dlx
+pnpm add -g @toon-protocol/client-mcp     # installs both bins
 ```
 
-This installs two bins: `toon-clientd` and `toon-mcp`.
+This installs two bins: `toon-clientd` and `toon-mcp`. To run a bin straight
+from npm without a global install, name it explicitly (the package name is not a
+bin, so plain `npx @toon-protocol/client-mcp` fails):
+
+```bash
+npx -y -p @toon-protocol/client-mcp toon-mcp       # MCP stdio server
+npx -y -p @toon-protocol/client-mcp toon-clientd   # daemon
+```
+
+## First run (zero-config onboarding)
+
+On the **first** `toon-clientd run`/`start` (including the auto-spawn from
+`toon-mcp`), the daemon onboards a brand-new user with no manual setup:
+
+- **Identity** — if no mnemonic is configured, it generates a fresh BIP-39
+  mnemonic, encrypts it to `~/.toon-client/keystore.json`, records
+  `keystorePath` in `config.json`, and prints the seed phrase + derived
+  addresses **once** (back it up). The keystore is encrypted with
+  `TOON_CLIENT_KEYSTORE_PASSWORD` when set, otherwise a default password so the
+  identity reloads on every restart with **no env var required**.
+- **Transport scaffolding** — it writes a starter `~/.toon-client/config.json`
+  carrying the `btpUrl`/`relayUrl`/`managedAnonProxy` knobs plus a `_help`
+  block documenting direct-vs-`.anyone` selection.
+
+The one thing you must supply is the apex you pay: set **`btpUrl`** (and usually
+`relayUrl`) in the scaffolded config, then publish. Everything below is for
+overriding those auto-provisioned defaults.
 
 ## Configure the daemon
 
 The daemon reads `~/.toon-client/config.json` (override with `TOON_CLIENT_CONFIG`).
-The **mnemonic is never stored in plaintext by default** — supply it via env or an
-encrypted keystore (scrypt + AES-256-GCM, mode 0600).
+The **mnemonic is never stored in plaintext by default** — it is auto-generated
+into an encrypted keystore (scrypt + AES-256-GCM, mode 0600) on first run, or you
+can supply your own via env or an imported keystore.
 
 ```jsonc
 // ~/.toon-client/config.json
@@ -96,9 +123,23 @@ Environment overrides: `TOON_CLIENT_MNEMONIC`, `TOON_CLIENT_KEYSTORE_PASSWORD`,
 `TOON_CLIENT_BTP_URL`, `TOON_CLIENT_RELAY_URL`, `TOON_CLIENT_SOCKS`,
 `TOON_CLIENT_HTTP_PORT`, `TOON_CLIENT_NETWORK`, `TOON_CLIENT_HOME`.
 
-The managed `.anyone` SOCKS5h proxy auto-starts when `btpUrl` is a `.anyone`
-host and no explicit `socksProxy` is set. The first bootstrap pays the anon
-warm-up cost (~30–90s) **once** — the detached daemon then stays up.
+**Transport is inferred from the URLs — no separate "direct vs hidden-service"
+switch.** The daemon parses the host of each URL independently:
+
+- `btpUrl`/`relayUrl` on a normal host (`ws://1.2.3.4:3000/btp`, `wss://…`) →
+  **direct**, dialed as-is.
+- `btpUrl` on a `.anyone` host → the ToonClient auto-starts a managed `anon`
+  SOCKS5h proxy and routes paid writes (and reads) through it.
+- `btpUrl` **direct** but `relayUrl` on a `.anyone` host → the daemon starts its
+  own managed `anon` proxy just for the free-read subscription; paid writes stay
+  direct. (Mixed transports — a direct apex with a hidden-service relay — work
+  out of the box.)
+
+No explicit `socksProxy` is needed for any of these. Set `socksProxy` only to
+point at your own external proxy, or `managedAnonProxy: false` to opt out of the
+managed proxy entirely. The first bootstrap pays the anon warm-up cost (~30–90s)
+**once** — the detached daemon then stays up. A read-proxy failure surfaces under
+`relay.proxyError` in `toon_status` and never blocks direct paid writes.
 
 ### Create an encrypted keystore
 

package/dist/{chunk-QHNSETFB.js → chunk-ARFPM2PT.js}

@@ -2243,6 +2243,7 @@ var base58 = /* @__PURE__ */ genBase58("123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefg
 var createBase58check = (sha2563) => /* @__PURE__ */ chain(checksum(4, (data) => sha2563(sha2563(data))), base58);
 
 // ../../node_modules/.pnpm/@scure+bip39@1.6.0/node_modules/@scure/bip39/esm/index.js
+var isJapanese = (wordlist2) => wordlist2[0] === "\u3042\u3044\u3053\u304F\u3057\u3093";
 function nfkd(str) {
   if (typeof str !== "string")
     throw new TypeError("invalid mnemonic type: " + typeof str);
@@ -2258,6 +2259,12 @@ function normalize(str) {
 function aentropy(ent) {
   abytes(ent, 16, 20, 24, 28, 32);
 }
+function generateMnemonic(wordlist2, strength = 128) {
+  anumber(strength);
+  if (strength % 32 !== 0 || strength > 256)
+    throw new TypeError("Invalid entropy");
+  return entropyToMnemonic(randomBytes(strength / 8), wordlist2);
+}
 var calcChecksum = (entropy) => {
   const bitsLeft = 8 - entropy.length / 4;
   return new Uint8Array([sha2562(entropy)[0] >> bitsLeft << bitsLeft]);
@@ -2277,6 +2284,11 @@ function mnemonicToEntropy(mnemonic, wordlist2) {
   aentropy(entropy);
   return entropy;
 }
+function entropyToMnemonic(entropy, wordlist2) {
+  aentropy(entropy);
+  const words = getCoder(wordlist2).encode(entropy);
+  return words.join(isJapanese(wordlist2) ? "\u3000" : " ");
+}
 function validateMnemonic(mnemonic, wordlist2) {
   try {
     mnemonicToEntropy(mnemonic, wordlist2);
@@ -6589,6 +6601,9 @@ var ValidationError = class extends ToonClientError {
     this.name = "ValidationError";
   }
 };
+function generateMnemonic2() {
+  return generateMnemonic(wordlist, 128);
+}
 function validateMnemonic2(mnemonic) {
   return validateMnemonic(mnemonic, wordlist);
 }
@@ -10409,6 +10424,8 @@ var SCRYPT_R = 8;
 var SCRYPT_P = 1;
 var SCRYPT_KEY_LEN = 32;
 var SCRYPT_MAXMEM = SCRYPT_N * SCRYPT_R * 256 + 32 * 1024 * 1024;
+var SALT_LEN = 32;
+var IV_LEN = 12;
 var AUTH_TAG_LEN = 16;
 function assertNode() {
   const versions = globalThis.process?.versions;
@@ -10418,6 +10435,42 @@ function assertNode() {
     );
   }
 }
+function encryptMnemonic2(mnemonic, password) {
+  assertNode();
+  if (typeof mnemonic !== "string" || mnemonic.length === 0) {
+    throw new Error("encryptMnemonic: mnemonic must be a non-empty string");
+  }
+  if (typeof password !== "string" || password.length === 0) {
+    throw new Error("encryptMnemonic: password must be a non-empty string");
+  }
+  const salt = randomBytes2(SALT_LEN);
+  const iv = randomBytes2(IV_LEN);
+  const key = scryptSync(password, salt, SCRYPT_KEY_LEN, {
+    N: SCRYPT_N,
+    r: SCRYPT_R,
+    p: SCRYPT_P,
+    maxmem: SCRYPT_MAXMEM
+  });
+  try {
+    const cipher = createCipheriv("aes-256-gcm", key, iv, {
+      authTagLength: AUTH_TAG_LEN
+    });
+    const ciphertext = Buffer.concat([
+      cipher.update(mnemonic, "utf8"),
+      cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    return {
+      salt: salt.toString("base64"),
+      iv: iv.toString("base64"),
+      ciphertext: ciphertext.toString("base64"),
+      tag: tag.toString("base64"),
+      version: 1
+    };
+  } finally {
+    key.fill(0);
+  }
+}
 function decryptMnemonic2(encrypted, password) {
   assertNode();
   if (typeof password !== "string" || password.length === 0) {
@@ -10456,6 +10509,13 @@ function decryptMnemonic2(encrypted, password) {
     key.fill(0);
   }
 }
+function generateKeystore(path, password) {
+  assertNode();
+  const mnemonic = generateMnemonic2();
+  const keystore = encryptMnemonic2(mnemonic, password);
+  writeKeystoreFile(path, keystore);
+  return { mnemonic, keystore };
+}
 function loadKeystore(path, password) {
   assertNode();
   const raw = readFileSync2(path, "utf8");
@@ -10467,11 +10527,19 @@ function loadKeystore(path, password) {
   }
   return decryptMnemonic2(parsed, password);
 }
+function writeKeystoreFile(path, keystore) {
+  assertNode();
+  writeFileSync2(path, JSON.stringify(keystore, null, 2), {
+    encoding: "utf8",
+    mode: 384
+  });
+}
 
 // src/daemon/config.ts
 import { readFileSync as readFileSync3 } from "fs";
 import { homedir } from "os";
 import { join as join2 } from "path";
+var DEFAULT_KEYSTORE_PASSWORD = "toon-client-default";
 function configDir() {
   return process.env["TOON_CLIENT_HOME"] ?? join2(homedir(), ".toon-client");
 }
@@ -10492,7 +10560,7 @@ function resolveMnemonic(file) {
   const envMnemonic = process.env["TOON_CLIENT_MNEMONIC"];
   if (envMnemonic) return envMnemonic.trim();
   if (file.keystorePath) {
-    const password = process.env["TOON_CLIENT_KEYSTORE_PASSWORD"];
+    const password = process.env["TOON_CLIENT_KEYSTORE_PASSWORD"] ?? (file.keystoreAutoPassword ? DEFAULT_KEYSTORE_PASSWORD : void 0);
     if (!password) {
       throw new Error(
         "keystorePath is set but TOON_CLIENT_KEYSTORE_PASSWORD is not provided"
@@ -10524,20 +10592,29 @@ function resolveConfig(file) {
   const chain2 = process.env["TOON_CLIENT_CHAIN"] ?? file.chain ?? "evm";
   const apex = file.apexChains?.[chain2] ?? file.apex;
   const managedPort = Number(file.managedAnonSocksPort ?? 9050);
-  const wantManaged = file.managedAnonProxy ?? (explicitSocks ? false : isAnyoneHost2(btpUrl));
+  const allowManaged = file.managedAnonProxy ?? true;
+  const btpIsAnyone = isAnyoneHost2(btpUrl);
+  const relayIsAnyone = isAnyoneHost2(relayUrl);
   let transport;
   let managedAnonProxy;
   let managedAnonSocksPort;
   let readsSocksProxy;
+  let manageReadProxy = false;
   if (explicitSocks) {
     transport = { type: "socks5", socksProxy: explicitSocks };
     managedAnonProxy = false;
     readsSocksProxy = explicitSocks;
-  } else if (wantManaged) {
+  } else if (allowManaged && btpIsAnyone) {
     transport = { type: "direct" };
     managedAnonProxy = true;
     managedAnonSocksPort = managedPort;
     readsSocksProxy = `socks5h://127.0.0.1:${managedPort}`;
+  } else if (allowManaged && relayIsAnyone) {
+    transport = { type: "direct" };
+    managedAnonProxy = false;
+    manageReadProxy = true;
+    managedAnonSocksPort = managedPort;
+    readsSocksProxy = `socks5h://127.0.0.1:${managedPort}`;
   } else {
     transport = { type: "direct" };
     managedAnonProxy = false;
@@ -10581,6 +10658,8 @@ function resolveConfig(file) {
     httpPort,
     relayUrl,
     ...readsSocksProxy !== void 0 ? { socksProxy: readsSocksProxy } : {},
+    manageReadProxy,
+    ...manageReadProxy ? { readProxySocksPort: managedPort } : {},
     destination,
     feePerEvent,
     apex,
@@ -10795,7 +10874,10 @@ export {
   encodeEventToToon,
   decodeEventFromToon,
   buildIlpPrepare,
+  deriveFullIdentity,
   ToonClient,
+  generateKeystore,
+  DEFAULT_KEYSTORE_PASSWORD,
   configDir,
   defaultConfigPath,
   readConfigFile,
@@ -10831,4 +10913,4 @@ export {
 @scure/bip32/lib/esm/index.js:
   (*! scure-bip32 - MIT License (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com) *)
 */
-//# sourceMappingURL=chunk-QHNSETFB.js.map
+//# sourceMappingURL=chunk-ARFPM2PT.js.map