@totalreclaw/totalreclaw 3.3.1-rc.8 → 3.3.1

package/llm-client.ts

@@ -908,6 +908,7 @@ async function chatCompletionAnthropic(
 // ---------------------------------------------------------------------------
 
 // Embeddings are now generated locally via @huggingface/transformers
-// (Harrier-OSS-v1-270M ONNX model). No API key needed.
-// See embedding.ts for implementation details.
-export { generateEmbedding, getEmbeddingDims } from './embedding.js';
+// (Harrier-OSS-v1-270M ONNX model). No API key needed. The native deps +
+// model are lazy-fetched from a pinned GitHub Release on first call —
+// see embedding.ts + embedder-loader.ts.
+export { generateEmbedding, getEmbeddingDims, getEmbeddingModelId, configureEmbedder } from './embedding.js';

package/lsh.ts

@@ -7,10 +7,15 @@
  * Default parameters: 32 bits per table, 20 tables.
  */
 
-// Lazy-load WASM to avoid crash when npm install hasn't finished yet.
+// Lazy-load WASM via createRequire. The shipped `dist/index.js` is ESM-only
+// (`"type":"module"`) so the bare `require` global is undefined at runtime.
+// See issue #124 for the bug this avoids; matches the pattern in
+// claims-helper / consolidation / digest-sync / pin / retype-setscope.
+import { createRequire } from 'node:module';
+const requireWasm = createRequire(import.meta.url);
 let _WasmLshHasher: typeof import('@totalreclaw/core')['WasmLshHasher'] | null = null;
 function getWasmLshHasher() {
-  if (!_WasmLshHasher) _WasmLshHasher = require('@totalreclaw/core').WasmLshHasher;
+  if (!_WasmLshHasher) _WasmLshHasher = requireWasm('@totalreclaw/core').WasmLshHasher;
   return _WasmLshHasher!;
 }
 

package/onboarding-cli.ts

@@ -59,6 +59,23 @@ import {
 // has one place to grow into later).
 // ---------------------------------------------------------------------------
 
+/**
+ * 3.3.1-rc.18 (issue #95) — deprecation warning for the interactive
+ * phrase-print branch. Emitted to STDERR (never stdout) so it is visible
+ * to humans but does not pollute any pipe consuming the wizard's output.
+ *
+ * The phrase-print branch will be REMOVED in the next RC after rc.18.
+ * Users running on a TTY can still complete the flow in rc.18; agents
+ * MUST use `--pair-only` or the `totalreclaw_pair` tool today.
+ */
+export const PHRASE_PRINT_DEPRECATION_WARNING =
+  '\nDEPRECATION (issue #95): the interactive `openclaw totalreclaw onboard` flow\n' +
+  '  prints your recovery phrase to this terminal. This is being removed in the\n' +
+  '  next release candidate. For agent / scripted invocation, use:\n' +
+  '    openclaw totalreclaw onboard --pair-only\n' +
+  '  which emits ONLY {pair_url, pin} JSON and routes the phrase through the\n' +
+  '  browser flow (never on stdout).\n\n';
+
 export const COPY = {
   welcome:
     '\nTotalReclaw — Secure onboarding\n\n' +
@@ -403,6 +420,11 @@ export async function runOnboardingWizard(deps: WizardDeps): Promise<WizardResul
   }
 
   if (choice === 'generate') {
+    // 3.3.1-rc.18 (issue #95) — deprecation banner on stderr ONLY.
+    // The phrase-print branch is scheduled for removal in the RC after
+    // rc.18; we keep it functional in rc.18 for back-compat with users
+    // running the wizard on a real TTY today.
+    io.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
     io.stdout.write(COPY.generateWarning);
     io.stdout.write(COPY.importRemoteLimitation);
     const mnemonic = genMnemonic();
@@ -674,6 +696,22 @@ export async function runNonInteractiveOnboard(
  *   --emit-phrase          Include the plaintext phrase in the JSON payload
  *                          (NOT recommended — the phrase lives in
  *                          credentials.json; prefer reading it there).
+ *
+ * 3.3.1-rc.18 — `onboard` accepts:
+ *   --pair-only            Phrase-safe agent-shell flag (issue #95).
+ *                          Delegates to the pair flow and emits a single
+ *                          line of JSON `{v, pair_url, pin, expires_at_ms}`
+ *                          to stdout. Phrase NEVER touches stdout, stderr,
+ *                          or the logger in this mode. Use this for any
+ *                          agent-driven setup; it is the recommended path
+ *                          when a container-based agent does not have the
+ *                          `totalreclaw_pair` tool injected.
+ *
+ *                          Requires `pairSessionsPath` + `renderPairingUrl`
+ *                          to be supplied to `registerOnboardingCli`. If
+ *                          absent, `--pair-only` exits non-zero with a
+ *                          clear message instead of falling through to the
+ *                          phrase-print branch.
  */
 export function registerOnboardingCli(
   program: import('commander').Command,
@@ -683,6 +721,10 @@ export function registerOnboardingCli(
     logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
     /** Caller-supplied helper for scope-address derivation. Optional — when absent, JSON output omits `scope_address`. */
     deriveScopeAddress?: (mnemonic: string) => Promise<string | undefined>;
+    /** Caller-supplied path to the pair-session store. Required for `--pair-only`. */
+    pairSessionsPath?: string;
+    /** Caller-supplied URL renderer for the pair flow. Required for `--pair-only`. */
+    renderPairingUrl?: (session: import('./pair-session-store.js').PairSession) => string;
   },
 ): void {
   const tr = program
@@ -690,12 +732,13 @@ export function registerOnboardingCli(
     .description('TotalReclaw encrypted memory — secure onboarding + status');
 
   tr.command('onboard')
-    .description('Interactive onboarding: generate or import a recovery phrase (runs locally, no LLM)')
+    .description('Interactive onboarding: generate or import a recovery phrase (runs locally, no LLM). For agent-driven setup prefer --pair-only.')
     .option('--non-interactive', 'Exit non-zero if any input would be prompted for (agent-driven use)')
     .option('--json', 'Emit the result as a structured JSON payload. Only valid with --non-interactive.')
     .option('--mode <mode>', 'generate | restore — skip the menu prompt')
     .option('--phrase <phrase>', 'Recovery phrase for --mode restore. `-` reads from stdin.')
     .option('--emit-phrase', 'Include the plaintext phrase in the JSON payload (not recommended). Default: false.')
+    .option('--pair-only', 'Phrase-safe agent-invocation mode (issue #95). Emits ONLY {v,pair_url,pin,expires_at_ms} JSON to stdout via the pair flow. Phrase never touches stdout/stderr/logger. RECOMMENDED for any agent or scripted invocation.')
     .action(async (...actionArgs: unknown[]) => {
       // commander: (options, cmd)
       const cliOpts = (actionArgs[0] ?? {}) as {
@@ -704,8 +747,70 @@ export function registerOnboardingCli(
         mode?: string;
         phrase?: string;
         emitPhrase?: boolean;
+        pairOnly?: boolean;
       };
 
+      // ---------------------------------------------------------------
+      // 3.3.1-rc.18 — `--pair-only` (issue #95)
+      //
+      // Phrase-safe agent-shell flag. Delegates to the pair flow and
+      // emits a single line of JSON `{v, pair_url, pin, expires_at_ms}`
+      // to stdout. By construction:
+      //   - The pair flow is x25519-only — pair-crypto.ts does NOT
+      //     import @scure/bip39 and never touches a recovery phrase.
+      //   - No interactive prompts, no readline, no @scure/bip39 import
+      //     in this code path. Phrase never enters stdout/stderr/logger.
+      //   - Stays silent on status transitions (the runPairCli
+      //     `pair-only` output mode suppresses banners, spinners, and
+      //     all human-readable copy).
+      //
+      // This MUST be the path agents take when they need to set up
+      // TotalReclaw via a shell. The interactive phrase-print branch
+      // below is deprecated for that use case and emits a warning when
+      // the user falls through to it.
+      // ---------------------------------------------------------------
+      if (cliOpts.pairOnly) {
+        if (!opts.pairSessionsPath || !opts.renderPairingUrl) {
+          process.stderr.write(
+            '--pair-only is unavailable: this OpenClaw build did not wire the pair flow into the onboard CLI. ' +
+              'Use `openclaw totalreclaw pair generate --url-pin-only` instead.\n',
+          );
+          process.exit(1);
+        }
+        // Resolve mode. --mode restore is incompatible with --pair-only
+        // since pair flow's "import" mode runs in the browser, not in
+        // the CLI. Default to 'generate' silently.
+        const pairMode = cliOpts.mode === 'restore' || cliOpts.mode === 'import' ? 'import' : 'generate';
+
+        // Lazy import — keeps pair-cli + qrcode-terminal off the
+        // onboarding hot path when --pair-only is not used.
+        const { runPairCli, defaultRenderQr, buildDefaultPairCliIo } = await import('./pair-cli.js');
+        const io = buildDefaultPairCliIo();
+        try {
+          const outcome = await runPairCli(pairMode, {
+            sessionsPath: opts.pairSessionsPath,
+            renderPairingUrl: opts.renderPairingUrl,
+            renderQr: defaultRenderQr,
+            io,
+            outputMode: 'pair-only',
+          });
+          if (outcome.status !== 'completed') {
+            process.exit(outcome.status === 'canceled' ? 130 : 1);
+          }
+          process.exit(0);
+        } catch (err) {
+          // CRITICAL: this catch MUST NOT include the phrase, the
+          // mnemonic, or any user secret in the message. The pair flow
+          // does not produce phrase material, so this is structurally
+          // safe — but defense-in-depth: emit a fixed error string.
+          opts.logger.error(
+            `pair-only delegation crashed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.stderr.write('--pair-only failed (see logs).\n');
+          process.exit(2);
+        }
+      }
+
       if (cliOpts.nonInteractive) {
         // Non-interactive path — no readline, no prompts.
         const mode: 'generate' | 'restore' | null =
@@ -744,10 +849,18 @@ export function registerOnboardingCli(
         });
 
         if (cliOpts.json) {
+          // 3.3.1-rc.18 (issue #95) — emit deprecation on stderr when
+          // the JSON payload is about to include the plaintext phrase.
+          // stderr is intentional: stdout must remain a single
+          // machine-parseable JSON line.
+          if (cliOpts.emitPhrase && result.ok && result.mnemonic) {
+            process.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
+          }
           process.stdout.write(JSON.stringify(result) + '\n');
         } else {
           if (result.ok) {
             if (result.mnemonic) {
+              process.stderr.write(PHRASE_PRINT_DEPRECATION_WARNING);
               process.stderr.write(
                 'WARNING: --emit-phrase was set. The plaintext recovery phrase was returned.\n' +
                   'For agent-driven flows, prefer reading ~/.totalreclaw/credentials.json directly ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.8",
+  "version": "3.3.1",
   "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": [
@@ -33,11 +33,22 @@
   "dependencies": {
     "@totalreclaw/client": "^1.2.0",
     "@totalreclaw/core": "^2.1.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/ws": "^8.5.12",
+    "qrcode": "^1.5.4",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.3"
+  },
+  "//": "@huggingface/transformers + onnxruntime-node deliberately omitted from runtime deps. They are heavy native bundles (~700 MB peak install RAM) that OOM-killed the OpenClaw gateway on small VPS during `openclaw plugins install` in rc.21 (issue: 3.7 GB Hetzner host). rc.22 ships them via a lazy GitHub-Releases bundle (`embedder-v1.tar.gz`) downloaded on first call to embed(). See `embedder-network.ts` + `scripts/build-embedder-bundle.mjs`. The dev-deps below are for type-checking + bundle generation only; npm install of the plugin tarball never installs them.",
+  "devDependencies": {
     "@huggingface/transformers": "^4.0.1",
     "onnxruntime-node": "^1.24.0",
-    "qrcode-terminal": "^0.12.0"
+    "typescript": "^5.5.0"
   },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "files": [
+    "dist/",
     "*.ts",
     "import-adapters/",
     "!**/*.test.ts",
@@ -50,13 +61,21 @@
     "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 && npx tsx phrase-safety-registry.test.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.json --noCheck",
+    "verify-tarball": "node ../scripts/verify-tarball.mjs",
+    "test": "npx tsx manifest-shape.test.ts && npx tsx config-schema.test.ts && npx tsx config.test.ts && npx tsx relay-headers.test.ts && npx tsx scope-address-visible.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 pair-qr.test.ts && npx tsx pair-remote-client.test.ts && npx tsx qa-bug-report.test.ts && npx tsx nonce-serialization.test.ts && npx tsx phrase-safety-registry.test.ts && npx tsx test_issue_92_onnx_download_ux.test.ts && npx tsx onboard-pair-only.test.ts && npx tsx import-time-smoke.test.ts && npx tsx install-staging-cleanup.test.ts && npx tsx partial-install-detection.test.ts && npx tsx install-reload-idempotency.test.ts && npx tsx json-stdout-cleanliness.test.ts",
+    "smoke:dist": "npx tsx dist-esm-smoke.test.ts",
     "check-scanner": "node ../scripts/check-scanner.mjs",
-    "prepublishOnly": "node ../scripts/check-scanner.mjs"
+    "check-version-drift": "node ../scripts/check-version-drift.mjs",
+    "sync-version": "node ../scripts/sync-version.mjs",
+    "preinstall": "node -e \"try{require('fs').writeFileSync('.tr-partial-install','');}catch{}\"",
+    "postinstall": "node -e \"try{require('fs').unlinkSync('.tr-partial-install');}catch{}\"",
+    "prepack": "npm run build",
+    "prepublishOnly": "node ../scripts/check-scanner.mjs && node ../scripts/check-version-drift.mjs"
   },
   "openclaw": {
     "extensions": [
-      "./index.ts"
+      "./dist/index.js"
     ]
   }
 }

package/pair-cli.ts

@@ -85,8 +85,22 @@ export interface PairCliOutcome {
  *     as the session reaches a terminal state — same status-code
  *     semantics as 'human' (0 on completed, 1 on expired/rejected/error,
  *     130 on canceled).
+ *   - 'url-pin': (3.3.1-rc.15, issue #87) headless container-agent fallback.
+ *     Emits ONLY `{ v, url, pin, expires_at_ms }` — no QR ASCII, no SID,
+ *     no mode echo. Use when a container-based agent cannot see the
+ *     `totalreclaw_pair` tool (OpenClaw gateway-to-container tool-injection
+ *     gap) and must shell out to the CLI. Guarantees zero phrase material
+ *     on stdout by construction — pair-crypto is x25519-only and the slim
+ *     payload carries nothing BIP-39-adjacent.
+ *   - 'pair-only': (3.3.1-rc.18, issue #95) the same surface as 'url-pin',
+ *     but the URL field is named `pair_url` (matching the spec wording
+ *     for `openclaw totalreclaw onboard --pair-only`). Used by the
+ *     onboard CLI's `--pair-only` flag to provide a phrase-safe
+ *     alternative to the interactive phrase-print path. Emits ONLY
+ *     `{ v, pair_url, pin, expires_at_ms }`. Same zero-phrase invariant
+ *     as 'url-pin' — the underlying pair flow does no BIP-39 work.
  */
-export type PairCliOutputMode = 'human' | 'json';
+export type PairCliOutputMode = 'human' | 'json' | 'url-pin' | 'pair-only';
 
 /**
  * JSON payload emitted by runPairCli when outputMode === 'json'. Printed
@@ -103,6 +117,31 @@ export interface PairCliJsonPayload {
   qr_ascii: string;
 }
 
+/**
+ * Slim payload for outputMode === 'url-pin'. Intentionally a subset of
+ * `PairCliJsonPayload` with no QR ASCII, SID, or mode echo. Issue #87.
+ */
+export interface PairCliUrlPinPayload {
+  v: 1;
+  url: string;
+  pin: string;
+  expires_at_ms: number;
+}
+
+/**
+ * Slim payload for outputMode === 'pair-only'. Same shape as
+ * `PairCliUrlPinPayload` but with `pair_url` instead of `url` — the
+ * key name matches the spec for `onboard --pair-only` (issue #95).
+ * Phrase invariant: zero BIP-39 material on stdout by construction
+ * (the pair flow is x25519-only).
+ */
+export interface PairCliPairOnlyPayload {
+  v: 1;
+  pair_url: string;
+  pin: string;
+  expires_at_ms: number;
+}
+
 // ---------------------------------------------------------------------------
 // Default stdout IO
 // ---------------------------------------------------------------------------
@@ -213,9 +252,13 @@ export async function runPairCli(
     return { status: 'error', error: msg };
   }
 
-  // 2. Render the QR — promise-based so both human + json modes share it.
+  // 2. Build the URL unconditionally, but only render the QR for modes
+  //    that actually emit it. url-pin and pair-only modes skip the
+  //    renderer entirely — no CPU cost, no qrcode-terminal import, no
+  //    ASCII on stdout.
   const url = deps.renderPairingUrl(session);
-  const qrAscii = await new Promise<string>((resolve) => {
+  const skipsQr = outputMode === 'url-pin' || outputMode === 'pair-only';
+  const qrAscii = skipsQr ? '' : await new Promise<string>((resolve) => {
     // Guard against QR renderers that never fire their callback (shouldn't
     // happen with qrcode-terminal, but defensive): a 10-second timeout
     // returns an empty string so we never hang the pairing flow.
@@ -241,8 +284,25 @@ export async function runPairCli(
     }
   });
 
-  // 3. Emit the visible surface (JSON first — single line — or human copy).
-  if (outputMode === 'json') {
+  // 3. Emit the visible surface (JSON/url-pin/pair-only first — single
+  //    line — or human copy).
+  if (outputMode === 'url-pin') {
+    const payload: PairCliUrlPinPayload = {
+      v: 1,
+      url,
+      pin: session.secondaryCode,
+      expires_at_ms: session.expiresAtMs,
+    };
+    stdout.write(JSON.stringify(payload) + '\n');
+  } else if (outputMode === 'pair-only') {
+    const payload: PairCliPairOnlyPayload = {
+      v: 1,
+      pair_url: url,
+      pin: session.secondaryCode,
+      expires_at_ms: session.expiresAtMs,
+    };
+    stdout.write(JSON.stringify(payload) + '\n');
+  } else if (outputMode === 'json') {
     const payload: PairCliJsonPayload = {
       v: 1,
       sid: session.sid,
@@ -276,7 +336,10 @@ export async function runPairCli(
     canceled = true;
   });
 
-  // 5. Poll
+  // 5. Poll — status transitions only surface in human mode; json /
+  //    url-pin / pair-only modes stay silent after the single payload
+  //    line so agents parsing stdout get one JSON line and an exit
+  //    code, nothing else.
   const emitStatus = (text: string): void => {
     if (outputMode === 'human') stdout.write(text);
   };
@@ -399,14 +462,19 @@ export function registerPairCli(
       'Pair a remote browser device to this gateway (mode = generate | import; default generate)',
     )
     .option('--json', 'Emit a single JSON payload (url/pin/sid/qr_ascii) instead of the human-readable banner. Enables agent-driven pairing.')
+    .option('--url-pin-only', 'Emit ONLY {v,url,pin,expires_at_ms} — no QR ASCII, no SID, no mode echo. Headless fallback for container-based agents where the totalreclaw_pair tool is not injected (issue #87). Zero phrase exposure on stdout.')
     .option('--timeout <sec>', 'Session TTL in seconds (default: 900 = 15 min, matches pair-session-store default)')
     .action(async (...args: unknown[]) => {
       // commander passes: [modeArg, options, cmd]
       const modeRaw = typeof args[0] === 'string' ? args[0] : undefined;
-      const opts = (args[1] ?? {}) as { json?: boolean; timeout?: string | number };
+      const opts = (args[1] ?? {}) as { json?: boolean; urlPinOnly?: boolean; timeout?: string | number };
       const mode: PairCliMode =
         modeRaw === 'import' || modeRaw === 'imp' ? 'import' : 'generate';
-      const outputMode: PairCliOutputMode = opts.json ? 'json' : 'human';
+      // --url-pin-only wins over --json when both are passed, since it is
+      // strictly the tighter surface (no QR, no SID). The flag is a subset.
+      const outputMode: PairCliOutputMode = opts.urlPinOnly
+        ? 'url-pin'
+        : opts.json ? 'json' : 'human';
       let ttlSeconds: number | undefined;
       if (typeof opts.timeout === 'number' && Number.isFinite(opts.timeout)) {
         ttlSeconds = opts.timeout;

package/pair-crypto.ts

@@ -1,19 +1,24 @@
 /**
- * pair-crypto — gateway-side cryptographic primitives for the v3.3.0
- * QR-pairing flow.
+ * pair-crypto — gateway-side cryptographic primitives for the v3.3.x
+ * relay-brokered pair flow.
  *
- * Cipher suite (per design doc section 3a-3b, ratified 2026-04-20):
+ * Cipher suite (design doc 3a-3b, cipher swap ratified 2026-04-23 / rc.12):
  *   - ECDH on x25519 for key agreement.
  *   - HKDF-SHA256 for symmetric-key derivation from the shared secret.
- *   - ChaCha20-Poly1305 AEAD for the ciphertext payload, with the sid
- *     bound as associated data (AD = sid UTF-8 bytes).
+ *   - AES-256-GCM AEAD for the ciphertext payload, with the sid bound as
+ *     associated data (AD = sid UTF-8 bytes, 12-byte nonce, 16-byte tag).
+ *
+ * rc.4..rc.11 used ChaCha20-Poly1305, but the Web Crypto API does NOT
+ * implement ChaCha20-Poly1305 in Chrome / Safari / Edge. The pair-page
+ * submit path silently threw `Algorithm: Unrecognized name` before
+ * reaching the network. rc.12 swaps the cipher suite to AES-256-GCM
+ * (universally supported in WebCrypto) and bumps HKDF_INFO to v2 so
+ * cross-version mis-pairs fail closed rather than garble.
  *
  * Every primitive is provided by the Node built-in `node:crypto` module
  * on Node 18.19+ and above. NO third-party crypto dependency is added
- * to the plugin for the gateway side. (The BROWSER side of the flow in
- * P2 uses WebCrypto with a `@noble/curves` + `@noble/ciphers` fallback
- * for older Safari — those ship as part of the served pairing page and
- * do NOT affect the plugin's server-side dep tree.)
+ * to the plugin for the gateway side. (The BROWSER side of the flow uses
+ * WebCrypto's AES-GCM directly — no shim needed.)
  *
  * Scope and guarantees
  * --------------------
@@ -33,11 +38,11 @@
  *
  * Interoperability with browser WebCrypto
  * ---------------------------------------
- *   The WebCrypto x25519 + HKDF + ChaCha20-Poly1305 APIs are bit-for-bit
- *   compatible with Node's `crypto` as long as:
+ *   The WebCrypto x25519 + HKDF + AES-GCM APIs are bit-for-bit compatible
+ *   with Node's `crypto` as long as:
  *     - Raw 32-byte public/private keys are used (not DER/SPKI).
  *     - HKDF parameters are (hash=SHA-256, salt=sid bytes, info fixed
- *       ASCII string, length=32 bytes → 256-bit AEAD key).
+ *       ASCII string "totalreclaw-pair-v2", length=32 bytes).
  *     - AEAD uses a 12-byte random nonce + 16-byte tag, AD = sid bytes.
  *   See tests for fixed test vectors.
  */
@@ -60,18 +65,23 @@ import {
 
 /**
  * HKDF "info" parameter — fixes the domain separation for this protocol.
- * MUST match the browser-side constant in the pair-page bundle (P2).
- * Versioned so we can roll to a new KDF without breaking old ciphertexts.
+ * MUST match the browser-side constant in the pair-page bundle + the
+ * relay-served pair-html page.
+ *
+ * Versioned so we can roll to a new KDF or cipher suite without silently
+ * producing garbage with old ciphertexts. rc.12: bumped from v1 to v2
+ * after cipher-suite swap from ChaCha20-Poly1305 → AES-256-GCM (see
+ * module header comment for context).
  */
-export const HKDF_INFO = 'totalreclaw-pair-v1';
+export const HKDF_INFO = 'totalreclaw-pair-v2';
 
-/** HKDF output length — 32 bytes = 256-bit ChaCha20-Poly1305 key. */
+/** HKDF output length — 32 bytes = 256-bit AES-256-GCM key. */
 export const AEAD_KEY_BYTES = 32;
 
-/** ChaCha20-Poly1305 nonce length — 12 bytes per RFC 7539. */
+/** AES-GCM nonce length — 12 bytes (SP 800-38D recommendation). */
 export const AEAD_NONCE_BYTES = 12;
 
-/** ChaCha20-Poly1305 auth tag length — 16 bytes standard. */
+/** AES-GCM auth tag length — 16 bytes (128 bits, standard). */
 export const AEAD_TAG_BYTES = 16;
 
 /** Raw x25519 public/private key length — 32 bytes per RFC 7748. */
@@ -101,7 +111,7 @@ export interface GatewayKeypair {
 
 /** Fully-derived session keys — caller uses kEnc for AEAD ops. */
 export interface SessionKeys {
-  /** 32-byte ChaCha20-Poly1305 key. */
+  /** 32-byte AES-256-GCM key. */
   kEnc: Buffer;
 }
 
@@ -323,9 +333,9 @@ export function deriveAeadKeyFromEcdh(opts: {
 // ---------------------------------------------------------------------------
 
 /**
- * Decrypt a ChaCha20-Poly1305 AEAD ciphertext. Returns the plaintext
- * on success; throws if the tag is invalid (which includes both
- * tampering and wrong-key attempts).
+ * Decrypt an AES-256-GCM AEAD ciphertext. Returns the plaintext on
+ * success; throws if the tag is invalid (which includes both tampering
+ * and wrong-key attempts).
  *
  * Ciphertext is expected in the combined form `plaintext || tag`, where
  * tag is the trailing 16 bytes. The caller MUST supply the same
@@ -351,7 +361,7 @@ export function aeadDecrypt(opts: {
   const ct = combined.subarray(0, combined.length - AEAD_TAG_BYTES);
   const tag = combined.subarray(combined.length - AEAD_TAG_BYTES);
 
-  const decipher = createDecipheriv('chacha20-poly1305', opts.kEnc, nonce, {
+  const decipher = createDecipheriv('aes-256-gcm', opts.kEnc, nonce, {
     authTagLength: AEAD_TAG_BYTES,
   });
   decipher.setAAD(Buffer.from(opts.sid, 'utf-8'), { plaintextLength: ct.length });
@@ -409,7 +419,7 @@ export function aeadEncryptWithSessionKey(opts: {
   }
 
   const pt = Buffer.isBuffer(opts.plaintext) ? opts.plaintext : Buffer.from(opts.plaintext);
-  const cipher = createCipheriv('chacha20-poly1305', opts.kEnc, nonceBuf, {
+  const cipher = createCipheriv('aes-256-gcm', opts.kEnc, nonceBuf, {
     authTagLength: AEAD_TAG_BYTES,
   });
   cipher.setAAD(Buffer.from(opts.sid, 'utf-8'), { plaintextLength: pt.length });

package/pair-page.ts

@@ -5,6 +5,17 @@
  * the URL fragment (`#pk=...`), runs the client-side pairing flow
  * ENTIRELY in the browser, and POSTs the encrypted payload back.
  *
+ * rc.13 status: this OpenClaw-plugin local-mode page has NOT been
+ * ported to the wizard UX used by the relay (production) and the
+ * Python local-mode pages. Local-mode on the OpenClaw plugin is rarely
+ * exercised — the plugin defaults to a relay flow via the Hermes
+ * Python sidecar and only falls back here for air-gapped setups. The
+ * wizard UX port for this file is tracked for rc.14 alongside the
+ * design decision on whether to share a single CSS+JS asset across
+ * all three pair pages (relay / Python / plugin) or keep them
+ * independently inlined. For now, this file retains its rc.10–rc.12
+ * UX shape and the rc.12 AES-GCM cipher swap.
+ *
  * Brand tokens imported from the v5b.html public site (colors, font
  * stack). Typography falls back to system fonts for mobile parity —
  * we don't ship Euclid Circular A bytes over the pairing HTTP surface.
@@ -364,7 +375,9 @@ button.secondary:hover:not(:disabled) { border-color: var(--border-accent); colo
   // Client-observed time at page load (used to adjust for clock skew).
   const CLIENT_EPOCH_AT_LOAD = Date.now();
 
-  const HKDF_INFO = "totalreclaw-pair-v1";
+  // v2: cipher-suite swap in rc.12 (see pair-crypto.ts header). Keep
+  // this constant in lockstep with the gateway-side pair-crypto.ts.
+  const HKDF_INFO = "totalreclaw-pair-v2";
 
   // ---------- Small utilities ----------
   function $(sel, root) { return (root || document).querySelector(sel); }
@@ -473,10 +486,9 @@ button.secondary:hover:not(:disabled) { border-color: var(--border-accent); colo
   }
 
   // ---------- Crypto shims: prefer WebCrypto; fall back to JS path ----------
-  // WebCrypto's x25519 + HKDF + ChaCha20-Poly1305 availability is Safari 17+
-  // and modern Chromium / Firefox. If absent we render an error — the page
-  // is self-contained, and we elect not to bundle @noble/curves + ciphers
-  // for the MVP (tracked as Wave 3.1 polish follow-up).
+  // WebCrypto's x25519 + HKDF + AES-GCM availability is Safari 17+ and
+  // modern Chromium 133+ / Firefox 130+. If absent we render an error
+  // — the page is self-contained and we do not bundle any JS crypto shim.
   async function ensureWebCryptoSupport() {
     if (!window.crypto || !crypto.subtle) return false;
     try {
@@ -505,29 +517,28 @@ button.secondary:hover:not(:disabled) { border-color: var(--border-accent); colo
     );
     return new Uint8Array(bits);
   }
-  // AEAD: WebCrypto offers AES-GCM universally; ChaCha20-Poly1305 support is
-  // newer. We attempt chacha first; if it throws, we abort (do NOT silently
-  // swap ciphers — that would mismatch the gateway).
-  async function aeadEncryptChaCha(keyBytes, nonce, sid, plaintext) {
+  // AEAD: AES-256-GCM (universal in WebCrypto). Cipher swap rationale
+  // lives in pair-crypto.ts header comment (rc.12 changelog entry).
+  async function aeadEncryptAesGcm(keyBytes, nonce, sid, plaintext) {
     const key = await crypto.subtle.importKey(
       "raw", keyBytes,
-      { name: "ChaCha20-Poly1305" },
+      { name: "AES-GCM" },
       false, ["encrypt"],
     );
     const adBytes = new TextEncoder().encode(sid);
     const ct = new Uint8Array(await crypto.subtle.encrypt(
-      { name: "ChaCha20-Poly1305", iv: nonce, additionalData: adBytes, tagLength: 128 },
+      { name: "AES-GCM", iv: nonce, additionalData: adBytes, tagLength: 128 },
       key, plaintext,
     ));
     return ct;
   }
 
-  async function chaChaSupported() {
+  async function aesGcmSupported() {
     try {
       const k = new Uint8Array(32);
       const n = new Uint8Array(12);
-      const key = await crypto.subtle.importKey("raw", k, { name: "ChaCha20-Poly1305" }, false, ["encrypt"]);
-      await crypto.subtle.encrypt({ name: "ChaCha20-Poly1305", iv: n, additionalData: new Uint8Array(0), tagLength: 128 }, key, new Uint8Array(0));
+      const key = await crypto.subtle.importKey("raw", k, { name: "AES-GCM" }, false, ["encrypt"]);
+      await crypto.subtle.encrypt({ name: "AES-GCM", iv: n, additionalData: new Uint8Array(0), tagLength: 128 }, key, new Uint8Array(0));
       return true;
     } catch (e) { return false; }
   }
@@ -742,8 +753,8 @@ button.secondary:hover:not(:disabled) { border-color: var(--border-accent); colo
       render(renderError("Your browser does not support modern cryptographic APIs (X25519). Please update your browser and try again, or use a different device. Supported: Chrome 123+, Firefox 130+, Safari 17+."));
       return;
     }
-    if (!(await chaChaSupported())) {
-      render(renderError("Your browser does not support ChaCha20-Poly1305. Update your browser or use a different device."));
+    if (!(await aesGcmSupported())) {
+      render(renderError("Your browser does not support AES-GCM. Update your browser or use a different device."));
       return;
     }
 
@@ -762,7 +773,7 @@ button.secondary:hover:not(:disabled) { border-color: var(--border-accent); colo
       const nonce = new Uint8Array(12);
       crypto.getRandomValues(nonce);
       const ptBytes = new TextEncoder().encode(mnemonic);
-      const ct = await aeadEncryptChaCha(kEnc, nonce, SID, ptBytes);
+      const ct = await aeadEncryptAesGcm(kEnc, nonce, SID, ptBytes);
 
       // 6. Zero sensitive buffers BEFORE sending. The JS GC will run
       //    whenever it runs; explicit zeroing is best-effort but honours