@totalreclaw/totalreclaw 1.0.3 → 1.0.4

package/README.md

@@ -46,6 +46,7 @@ TotalReclaw also ships a standalone MCP server for Claude Desktop, Cursor, and o
 | `totalreclaw_forget` | Delete a specific memory (on-chain tombstone) |
 | `totalreclaw_export` | Export all memories as plaintext |
 | `totalreclaw_status` | Check subscription tier and quota |
+| `totalreclaw_generate_recovery_phrase` | Generate a secure 12-word BIP-39 mnemonic (onboarding) |
 
 ## Lifecycle hooks
 

package/SKILL.md

@@ -208,6 +208,28 @@ Check subscription status and usage quota.
 
 ---
 
+### totalreclaw_generate_recovery_phrase
+
+Generate a cryptographically secure 12-word BIP-39 recovery phrase for new users. **Always use this tool** — never generate mnemonic words yourself.
+
+**Parameters:** None
+
+**Example:**
+```json
+{}
+```
+
+**Returns:**
+```json
+{
+  "mnemonic": "abandon ability able about above absent absorb abstract absurd abuse access accident",
+  "wordCount": 12,
+  "instructions": ["Display this phrase prominently to the user.", "..."]
+}
+```
+
+---
+
 ## Post-Install Setup
 
 After installing TotalReclaw, the agent MUST complete setup automatically. **Do NOT ask the user to set environment variables manually.**
@@ -227,7 +249,7 @@ The master password is a **12-word BIP-39 mnemonic** — like a crypto wallet se
 Ask the user:
 > "Do you have an existing TotalReclaw recovery phrase you'd like to restore, or should I generate a new one?"
 
-- **New user:** Generate a random 12-word BIP-39 mnemonic and set it as `TOTALRECLAW_MASTER_PASSWORD`. Then display it prominently with a warning:
+- **New user:** Call the `totalreclaw_generate_recovery_phrase` tool to generate a cryptographically secure 12-word BIP-39 mnemonic. **NEVER generate mnemonic words yourself** — always use this tool. Then set it as `TOTALRECLAW_MASTER_PASSWORD` and display it prominently with a warning:
   > "⚠️ SAVE YOUR RECOVERY PHRASE — it's the only way to recover your memories if you switch devices: `[phrase]`"
 - **Returning user:** Ask them to provide their existing 12-word phrase, then set it as `TOTALRECLAW_MASTER_PASSWORD`.
 

package/dist/index.js

@@ -9758,6 +9758,12 @@ function createHasher(hashCons, info = {}) {
   Object.assign(hashC, info);
   return Object.freeze(hashC);
 }
+function randomBytes(bytesLength = 32) {
+  const cr = typeof globalThis === "object" ? globalThis.crypto : null;
+  if (typeof cr?.getRandomValues !== "function")
+    throw new Error("crypto.getRandomValues must be defined");
+  return cr.getRandomValues(new Uint8Array(bytesLength));
+}
 var oidNist = (suffix) => ({
   oid: Uint8Array.from([6, 9, 96, 134, 72, 1, 101, 3, 4, 2, suffix])
 });
@@ -11512,6 +11518,7 @@ var utils = {
 };
 
 // node_modules/@scure/bip39/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);
@@ -11529,6 +11536,12 @@ function aentropy(ent) {
   if (![16, 20, 24, 28, 32].includes(ent.length))
     throw new Error("invalid entropy length");
 }
+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([sha256(entropy)[0] >> bitsLeft << bitsLeft]);
@@ -11548,6 +11561,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);
@@ -13629,6 +13647,9 @@ function isBip39Mnemonic(input) {
   if (words.length !== 12 && words.length !== 24) return false;
   return validateMnemonic(input.trim(), wordlist);
 }
+function generateSecureMnemonic() {
+  return generateMnemonic(wordlist, 128);
+}
 function deriveKeysFromMnemonic(mnemonic) {
   const seed = mnemonicToSeedSync(mnemonic.trim());
   const salt = Buffer.from(seed.slice(0, 32));
@@ -30952,7 +30973,7 @@ async function initialize(logger) {
     }
   }
 }
-var SETUP_ERROR_MSG = 'TotalReclaw setup required. Follow the "Post-Install Setup" steps in SKILL.md:\n1. Set TOTALRECLAW_MASTER_PASSWORD \u2014 ask the user if they have an existing recovery phrase or generate a new 12-word BIP-39 mnemonic.\n2. Set TOTALRECLAW_SUBGRAPH_MODE=true\n3. Restart the gateway to apply changes.';
+var SETUP_ERROR_MSG = 'TotalReclaw setup required. Follow the "Post-Install Setup" steps in SKILL.md:\n1. Set TOTALRECLAW_MASTER_PASSWORD \u2014 ask the user if they have an existing recovery phrase, or call totalreclaw_generate_recovery_phrase to generate a secure one.\n2. Set TOTALRECLAW_SUBGRAPH_MODE=true\n3. Restart the gateway to apply changes.';
 async function ensureInitialized(logger) {
   if (!initPromise) {
     initPromise = initialize(logger);
@@ -31688,6 +31709,40 @@ ${lines.join("\n")}`;
       },
       { name: "totalreclaw_status" }
     );
+    api.registerTool(
+      {
+        name: "totalreclaw_generate_recovery_phrase",
+        label: "Generate Recovery Phrase",
+        description: "Generate a cryptographically secure 12-word BIP-39 recovery phrase. Call this during onboarding when the user needs a new recovery phrase. NEVER generate mnemonics yourself \u2014 always use this tool.",
+        parameters: {
+          type: "object",
+          properties: {},
+          additionalProperties: false
+        },
+        execute() {
+          const mnemonic = generateSecureMnemonic();
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  mnemonic,
+                  wordCount: 12,
+                  instructions: [
+                    "Display this phrase prominently to the user.",
+                    "Warn them to save it \u2014 it is the ONLY way to recover their memories.",
+                    "Set it as TOTALRECLAW_MASTER_PASSWORD in the OpenClaw config.",
+                    "Set TOTALRECLAW_SUBGRAPH_MODE=true.",
+                    "Restart the gateway to apply changes."
+                  ]
+                })
+              }
+            ]
+          };
+        }
+      },
+      { name: "totalreclaw_generate_recovery_phrase" }
+    );
     api.on(
       "before_agent_start",
       async (event) => {
@@ -31700,7 +31755,7 @@ ${lines.join("\n")}`;
           await ensureInitialized(api.logger);
           if (needsSetup) {
             return {
-              prependContext: '## TotalReclaw Setup Required\n\nTotalReclaw is installed but needs configuration. Follow the "Post-Install Setup" steps in SKILL.md to complete setup.\nAsk the user: "Do you have an existing TotalReclaw recovery phrase, or should I generate a new one?"'
+              prependContext: '## TotalReclaw Setup Required\n\nTotalReclaw is installed but needs configuration. Follow the "Post-Install Setup" steps in SKILL.md to complete setup.\nAsk the user: "Do you have an existing TotalReclaw recovery phrase, or should I generate a new one?"\nIf they want a new one, call the `totalreclaw_generate_recovery_phrase` tool \u2014 NEVER generate mnemonic words yourself.'
             };
           }
           let billingWarning = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Zero-knowledge encrypted memory vault for AI agents — the password manager for AI memory.",
   "type": "module",
   "license": "MIT",