@totalreclaw/totalreclaw 3.3.1-rc.3 → 3.3.1-rc.4

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@totalreclaw/totalreclaw` (the OpenClaw plugin) are docu
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.1-rc.4] — 2026-04-22
+
+Phrase-safety hardening: `totalreclaw_onboard` agent tool removed. Paired with Hermes Python `2.3.1rc4` (which ports the QR-pair flow to Python so Hermes users gain a phrase-safe agent setup path too).
+
+### Removed (phrase-safety enforcement — BREAKING for agent tool callers)
+
+- **`totalreclaw_onboard` agent tool — REMOVED.** rc.3 shipped a `totalreclaw_onboard` tool that generated a fresh BIP-39 mnemonic in-process, wrote it to `credentials.json`, and returned `{scope_address, credentials_path}`. `emitPhrase: false` kept the mnemonic out of the tool's return payload, but NOTHING ARCHITECTURALLY PREVENTED leakage — a future patch could regress the flag, a different code path could echo the mnemonic in a log/error, or the mere existence of the tool signalled to agents that phrase generation inside chat is fine (it isn't). Per `project_phrase_safety_rule.md`: "recovery phrase MUST NEVER cross the LLM context in ANY form." rc.4 removes the registration. The underlying `runNonInteractiveOnboard` code path stays reachable via the CLI `openclaw totalreclaw onboard` — that path runs in the user's own terminal, OUTSIDE any agent shell, so phrase stdout never feeds back into LLM context.
+
+### Changed
+
+- **`SKILL.md` — setup section rewritten.** `totalreclaw_pair` is now the canonical setup surface for all users (local or remote). The CLI wizard (`openclaw totalreclaw onboard`) is explicitly documented as user-terminal-only — agents MUST NOT invoke it via their shell tool. Tool surface table updated: `totalreclaw_onboard` removed, `totalreclaw_pair` promoted to canonical. `totalreclaw_onboarding_start` remains as a pointer-only tool for users who explicitly prefer local-terminal setup.
+- **`index.ts` — `totalreclaw_pair` tool description updated.** Removed backref to `totalreclaw_onboard`; now instructs agents to always prefer pair, with `totalreclaw_onboarding_start` as the fallback pointer for local-terminal-only users.
+- **`docs/guides/openclaw-setup.md` — QR pairing is now documented as the default setup flow.** CLI wizard moved to a user-terminal-only subsection with a prominent "do NOT run this through an agent shell" warning.
+
+### Tests
+
+- **`phrase-safety-registry.test.ts`** — new. Text-scans `index.ts` for `api.registerTool({ name: '...' })` literals and asserts: (a) `totalreclaw_onboard` is NOT in the list; (b) `totalreclaw_pair` IS in the list; (c) no name contains phrase-adjacent tokens (`onboard_generate`, `generate_phrase`, `generate_mnemonic`, `restore_phrase`, `restore_mnemonic`, `mnemonic`). Runs as part of `npm test`.
+
 ## [3.3.1-rc.3] — 2026-04-22
 
 Patch RC bundling two stability fixes, one new RC-gated tool, two SKILL.md addendums, and a configurable LLM retry budget. All prior rc.1 + rc.2 fixes are preserved.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: totalreclaw
 description: "End-to-end encrypted memory for AI agents — portable, yours forever. XChaCha20-Poly1305 E2EE: server never sees plaintext."
-version: 3.3.1-rc.3
+version: 3.3.1-rc.4
 author: TotalReclaw Team
 license: MIT
 homepage: https://totalreclaw.xyz
@@ -30,14 +30,26 @@ You are operating inside a host that has the TotalReclaw memory plugin loaded. T
 
 Before any memory tool, check `~/.totalreclaw/credentials.json`:
 
-- **Missing, empty, malformed, or no `mnemonic` key** -> NOT set up. You MUST NOT generate a phrase in chat, and you MUST NOT ask the user to paste one. Route:
-  - Local gateway: call `totalreclaw_onboarding_start` (or `totalreclaw_onboard` if available); both return a pointer to `openclaw totalreclaw onboard`.
-  - Remote gateway (VPS / Docker / no TTY): call `totalreclaw_pair` (v3.3.1+), OR instruct the user to run `openclaw totalreclaw pair generate --json`. Present the returned `{url, pin, qr_ascii}` to the user. The phrase is entered in their browser, never in this conversation.
+- **Missing, empty, malformed, or no `mnemonic` key** -> NOT set up. Follow the "Setting up a user's TotalReclaw recovery phrase" section below. You MUST NOT generate a phrase in chat, and you MUST NOT ask the user to paste one.
 - **Present with a valid `mnemonic`** -> active. Use the tools below.
 
+## Setting up a user's TotalReclaw recovery phrase
+
+**Agent path (default, only secure path): call the `totalreclaw_pair` tool.** It returns a URL + 6-digit PIN. Tell the user:
+
+> "Open <URL> in your browser, enter your phrase (or let the browser generate one), and confirm PIN <PIN>. Your phrase is encrypted in the browser and uploaded end-to-end-encrypted to this gateway — it never crosses this chat."
+
+Browser-side crypto handles the phrase; this chat never sees it. After the user confirms "pairing complete" in their browser, the credentials are already on disk — no gateway restart needed for OpenClaw because routes are registered on plugin install and the pair HTTP handler writes credentials in-process.
+
+**NEVER** invoke `openclaw totalreclaw onboard`, `totalreclaw setup`, or any phrase-generating CLI via your shell tool. Those commands are for users to run in their own terminal — not for you. Agent shell stdout is captured into LLM context; running them leaks the phrase.
+
+**NEVER** ask the user to paste their phrase into chat. If they do, immediately tell them to rotate by generating a new wallet via `totalreclaw_pair` with `mode=generate`; the pasted phrase is compromised.
+
+**If the user explicitly prefers local-terminal setup** (no browser, no QR URL to open), point them at `totalreclaw_onboarding_start` — which returns a pointer to the CLI wizard they run THEMSELVES. You do not run it.
+
 ## Core rules
 
-1. **Phrase safety (NON-NEGOTIABLE).** The recovery phrase is a secret. Never generate one in chat, never echo one back, never log one in reasoning / tool payloads, never pass one to another tool. Direct users to `cat ~/.totalreclaw/credentials.json | jq -r .mnemonic`.
+1. **Phrase safety (NON-NEGOTIABLE, ABSOLUTE).** The recovery phrase is a secret. Never generate one in chat, never echo one back, never log one in reasoning / tool payloads, never pass one to another tool, never invoke a phrase-generating CLI via your shell tool. A leaked phrase = compromised vault, no rotation possible. Governed by `project_phrase_safety_rule.md` (memory file in p-diogo/totalreclaw-internal).
 2. **Use the tools, not inline state.** `totalreclaw_remember` stores; `totalreclaw_recall` retrieves. Don't re-ask the user for past facts; don't paraphrase memories as your own recollection.
 3. **Gateway restart is required after install.** If tools fail right after `openclaw plugins install @totalreclaw/totalreclaw`, tell the user to run `openclaw restart` or `docker restart openclaw-qa`.
 
@@ -87,8 +99,8 @@ Tools work only when credentials are active AND the gateway has been restarted p
 | `totalreclaw_migrate` | optional `confirm` (dry-run by default) |
 | `totalreclaw_import_from` / `totalreclaw_import_batch` | `source`, `file_path` or `content`, `dry_run` |
 | `totalreclaw_consolidate` | optional `dry_run` |
-| `totalreclaw_onboarding_start` / `totalreclaw_onboard` | (none) — returns CLI pointer |
-| `totalreclaw_pair` | optional `mode` (`generate` / `import`) — returns `{url, pin, qr_ascii, expires_at_ms}` |
+| `totalreclaw_onboarding_start` | (none) — returns CLI pointer for users who prefer local-terminal setup |
+| `totalreclaw_pair` | optional `mode` (`generate` / `import`) — returns `{url, pin, qr_ascii, expires_at_ms}`. CANONICAL setup surface |
 
 ## Taxonomy
 

package/index.ts

@@ -5049,143 +5049,34 @@ const plugin = {
     );
 
     // ---------------------------------------------------------------
-    // Tool: totalreclaw_onboard (3.3.1-rc.2 — agent-callable onboard)
+    // Tool: totalreclaw_onboard — REMOVED in 3.3.1-rc.4 (phrase-safety).
     //
-    // Lets the agent drive the non-interactive onboard flow without
-    // shelling out to `openclaw totalreclaw onboard` (subprocess work
-    // is not available inside the plugin runtime and the OpenClaw
-    // security scanner blocks the standard subprocess module).
+    // rc.3 shipped a `totalreclaw_onboard` agent tool that generated a
+    // fresh BIP-39 mnemonic in-process, wrote it to credentials.json,
+    // and returned `{scope_address, credentials_path}` to the agent.
+    // `emitPhrase: false` kept the mnemonic OUT of the tool's return
+    // payload, but NOTHING ARCHITECTURALLY PREVENTED leakage — a future
+    // patch could regress the flag, a different code path could echo
+    // the mnemonic in a log/error message the agent captures, or the
+    // mere existence of the tool implied to agents that "generating a
+    // phrase here is fine" (it isn't).
     //
-    // Security envelope (same as the CLI path):
-    //   - NEVER accepts a recovery phrase through chat (mode=restore
-    //     is rejected here — that still requires the local CLI wizard).
-    //   - The generated phrase is written to ~/.totalreclaw/credentials.json
-    //     (mode 0600) by `runNonInteractiveOnboard`. We explicitly pass
-    //     `emitPhrase: false` so the phrase NEVER appears in the tool
-    //     return value.
-    //   - Returns only: scope_address + credentials_path + ok/error.
+    // Per ``project_phrase_safety_rule.md``
+    // (memory file in p-diogo/totalreclaw-internal — absolute rule:
+    // "recovery phrase MUST NEVER cross the LLM context in ANY form"),
+    // phrase-generating agent tools are forbidden. The ONLY approved
+    // agent-facilitated setup surface is ``totalreclaw_pair`` (browser-
+    // side crypto keeps the phrase out of the LLM round-trip by
+    // construction). The underlying ``runNonInteractiveOnboard`` code
+    // path is still reachable via the CLI ``openclaw totalreclaw onboard``
+    // — that path runs in the user's own terminal, OUTSIDE any agent
+    // shell, so phrase stdout never feeds back into LLM context.
+    //
+    // Audit assertion: ``tool-gating.test.ts`` enforces the removal —
+    // any future re-registration of ``totalreclaw_onboard`` (or any
+    // phrase-generating variant like ``totalreclaw_onboard_generate``,
+    // ``totalreclaw_restore_phrase``) fails CI.
     // ---------------------------------------------------------------
-    api.registerTool(
-      {
-        name: 'totalreclaw_onboard',
-        label: 'Onboard (generate new recovery phrase)',
-        description:
-          'Generate a NEW TotalReclaw recovery phrase on this machine without the user ' +
-          'leaving chat. The phrase is written ONLY to ~/.totalreclaw/credentials.json (mode ' +
-          '0600) and NEVER returned through this tool — the response contains just the derived ' +
-          'Smart Account (scope) address and the credentials path so the user can retrieve ' +
-          'their phrase locally (e.g. `cat ~/.totalreclaw/credentials.json | jq -r .mnemonic`).\n\n' +
-          'Use when a fresh user asks you to set up TotalReclaw or enable memory. Refuses if ' +
-          'onboarding is already active (the user can delete the credentials file to re-onboard, ' +
-          'but we will NOT silently overwrite). For RESTORE (import an existing phrase), tell ' +
-          'the user to run `openclaw totalreclaw onboard --mode restore` in their local ' +
-          'terminal — this tool refuses to accept phrases through chat.',
-        parameters: {
-          type: 'object',
-          properties: {
-            mode: {
-              type: 'string',
-              enum: ['generate'],
-              description:
-                'Only "generate" is supported via this tool (creates a fresh 12-word BIP-39 ' +
-                'phrase). "restore" requires the local CLI wizard because pasting a phrase ' +
-                'through chat ships it to the LLM provider, defeating end-to-end encryption.',
-              default: 'generate',
-            },
-          },
-          additionalProperties: false,
-        },
-        async execute(_toolCallId: string, params: Record<string, unknown>) {
-          const mode = params?.mode;
-          if (mode !== undefined && mode !== 'generate') {
-            return {
-              content: [{
-                type: 'text',
-                text:
-                  'Only mode="generate" is supported through chat. For RESTORE (import an ' +
-                  'existing recovery phrase), ask the user to run `openclaw totalreclaw onboard ' +
-                  '--mode restore` in their local terminal — the phrase is read from stdin and ' +
-                  'never touches the LLM provider or the transcript.',
-              }],
-            };
-          }
-          try {
-            const result: NonInteractiveOnboardResult = await runNonInteractiveOnboard({
-              credentialsPath: CREDENTIALS_PATH,
-              statePath: CONFIG.onboardingStatePath,
-              mode: 'generate',
-              emitPhrase: false, // NEVER include the phrase in agent-visible output.
-              deriveScopeAddress: async (mnemonic: string) => {
-                try {
-                  return await deriveSmartAccountAddress(mnemonic, CONFIG.chainId);
-                } catch (err) {
-                  api.logger.warn(
-                    `totalreclaw_onboard: scope-address derivation failed: ${
-                      err instanceof Error ? err.message : String(err)
-                    }`,
-                  );
-                  return undefined;
-                }
-              },
-            });
-            if (!result.ok) {
-              // already-active, write-failed, etc. Never leaks the phrase.
-              api.logger.info(`totalreclaw_onboard: ok=false error=${result.error}`);
-              return {
-                content: [{
-                  type: 'text',
-                  text:
-                    result.error === 'already-active'
-                      ? 'TotalReclaw is already set up on this machine. Memory tools are unblocked. To re-onboard, delete ~/.totalreclaw/credentials.json first.'
-                      : `Onboard failed: ${result.error_detail ?? result.error}`,
-                }],
-                details: {
-                  ok: false,
-                  error: result.error,
-                  action: result.action,
-                },
-              };
-            }
-            api.logger.info(
-              `totalreclaw_onboard: generated phrase, scope=${result.scope_address?.slice(0, 10) ?? 'unknown'}…, credentials=${result.credentials_path}`,
-            );
-            // Crucially: the mnemonic field is NEVER emitted in details
-            // (emitPhrase=false enforces that on the result object).
-            return {
-              content: [{
-                type: 'text',
-                text:
-                  `TotalReclaw setup complete. A new 12-word recovery phrase was generated and ` +
-                  `saved to ${result.credentials_path} (mode 0600). ` +
-                  (result.scope_address
-                    ? `Your on-chain scope (Smart Account) address is ${result.scope_address}. `
-                    : '') +
-                  `To view your recovery phrase, run on the user's local terminal:\n\n` +
-                  `    cat ${result.credentials_path} | jq -r .mnemonic\n\n` +
-                  `IMPORTANT: the recovery phrase is the ONLY way to recover memories on another ` +
-                  `device. Tell the user to store it safely — a password manager or a paper backup. ` +
-                  `TotalReclaw cannot recover it if lost.`,
-              }],
-              details: {
-                ok: true,
-                action: 'generate',
-                scope_address: result.scope_address,
-                credentials_path: result.credentials_path,
-                // Deliberately NO mnemonic field.
-              },
-            };
-          } catch (err: unknown) {
-            const message = err instanceof Error ? err.message : String(err);
-            api.logger.error(`totalreclaw_onboard failed: ${message}`);
-            return {
-              content: [{ type: 'text', text: `Onboard failed: ${humanizeError(message)}` }],
-              details: { ok: false, error: 'unexpected', error_detail: message },
-            };
-          }
-        },
-      },
-      { name: 'totalreclaw_onboard' },
-    );
 
     // ---------------------------------------------------------------
     // Tool: totalreclaw_pair (3.3.1-rc.2 — agent-callable pair-generate)
@@ -5206,10 +5097,12 @@ const plugin = {
           '6-digit PIN, and an ASCII QR code that the agent relays to the user. The recovery ' +
           'phrase itself is generated/entered in the BROWSER and uploaded end-to-end encrypted ' +
           'to this gateway — it NEVER touches the LLM provider or the chat transcript.\n\n' +
-          'Use when a user wants to set up TotalReclaw on a machine they don\'t have terminal ' +
-          'access to (a VPS, a friend\'s computer), or when they prefer a phone-mediated flow. ' +
-          'For local-machine setup with a terminal, prefer `totalreclaw_onboard` (generate) or ' +
-          '`totalreclaw_onboarding_start` (pointer to local CLI for restore).',
+          'This is the CANONICAL agent-facilitated setup surface — use it whenever the user ' +
+          'asks you to set up TotalReclaw, regardless of whether they have terminal access. ' +
+          'Browser-side crypto keeps the recovery phrase out of the LLM context entirely. ' +
+          'If a user explicitly prefers local-terminal setup with no browser, point them at ' +
+          '`totalreclaw_onboarding_start` (a pointer to the CLI wizard they run on their own ' +
+          'terminal, NOT through your shell tool).',
         parameters: {
           type: 'object',
           properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.3",
+  "version": "3.3.1-rc.4",
   "description": "End-to-end encrypted, agent-portable memory for OpenClaw and any LLM-agent runtime. XChaCha20-Poly1305 with protobuf v4 + on-chain Memory Taxonomy v1 (claim / preference / directive / commitment / episode / summary).",
   "type": "module",
   "keywords": [
@@ -50,7 +50,7 @@
     "skill.json"
   ],
   "scripts": {
-    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx llm-profile-reader.test.ts && npx tsx llm-client.test.ts && npx tsx llm-client-retry.test.ts && npx tsx gateway-url.test.ts && npx tsx retype-setscope.test.ts && npx tsx tool-gating.test.ts && npx tsx onboarding-noninteractive.test.ts && npx tsx pair-cli-json.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
     "prepublishOnly": "node ../scripts/check-scanner.mjs"
   },