@totalreclaw/totalreclaw 3.3.1-rc.11 → 3.3.1-rc.13

package/CHANGELOG.md

@@ -4,6 +4,70 @@ 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.13] — 2026-04-24
+
+Coordinated version bump with Python `2.3.1rc13`. No substantive
+changes to the plugin's own TypeScript — the rc.13 fix lands on the
+Hermes-side (`python/src/totalreclaw/hermes/pair_tool.py`) where the
+asyncio lifecycle regression lived. We keep plugin + Python RC
+numbers in lockstep so the release-pipeline tracker and
+`qa-totalreclaw` skill carry both artifacts through QA as one
+bundle.
+
+See the corresponding entry in `python/CHANGELOG.md` for the full
+design: the relay-pair WebSocket is now owned by a dedicated worker
+thread (with its own event loop) so it survives the Hermes
+tool-invocation loop teardown that destroyed the rc.10–rc.12 waiter
+mid-recv and caused every pair attempt to 502.
+
+The relay-served production pair page is also replaced with the
+rc.13 wizard UX — a typeform-style 3-step flow (PIN → phrase → done)
+mirroring the `docs/mockups/rc13-pair-wizard/` design. This lands in
+the `totalreclaw-relay` repo PR, not here, but surfaces to every
+OpenClaw user via the default relay pair flow.
+
+### Plugin local-mode pair page
+
+`skill/plugin/pair-page.ts` (the local-mode fallback served when a
+user sets `TOTALRECLAW_PAIR_MODE=local`) retains its rc.10–rc.12 UX
+shape. The wizard UX port for this file is deferred to rc.14 pending
+a design decision on whether to share a single CSS+JS asset across
+all three pair pages (relay / Python local / plugin local) or keep
+them independently inlined. Local-mode is rarely exercised — the
+plugin defaults to the relay flow via the Hermes Python sidecar and
+only falls back here for air-gapped setups.
+
+## [3.3.1-rc.12] — 2026-04-23
+
+**Ship-stopper fix for rc.11.** The relay-served pair page's submit
+button threw `NotSupportedError: Failed to execute 'importKey' on
+'SubtleCrypto': Algorithm: Unrecognized name` when the user clicked
+"Seal key and finish". Root cause: `ChaCha20-Poly1305` is NOT
+implemented in the Web Crypto API of Chrome / Safari / Edge — the
+spec exposes `AES-GCM` as the only AEAD. rc.10/rc.11 never worked
+end-to-end for any user; every pair attempt failed silently and the
+token expired without logging a failure — GH issue #79.
+
+rc.12 swaps the cipher suite from ChaCha20-Poly1305 to AES-256-GCM on
+both sides (browser + gateway). Wire shape unchanged — still 12-byte
+nonce, 16-byte tag, sid-bound AAD, base64url encoding. HKDF info bumped
+from `totalreclaw-pair-v1` to `totalreclaw-pair-v2` so rc.11 ciphertexts
+cannot collide with rc.12 keys (fail-closed on any version skew).
+
+### Changed
+- `skill/plugin/pair-crypto.ts`: `aeadDecrypt` / `aeadEncryptWithSessionKey`
+  switched from `chacha20-poly1305` to `aes-256-gcm`. `HKDF_INFO` bumped
+  to `totalreclaw-pair-v2`.
+- `skill/plugin/pair-page.ts` (local-mode pair page): WebCrypto
+  `ChaCha20-Poly1305` calls swapped to `AES-GCM`. Capability probe
+  function renamed `chaChaSupported` → `aesGcmSupported`.
+
+### Observability
+- The relay's `pair-html.ts` (user-facing page) now reports phase-labelled
+  error messages so a network / encrypt / submit failure no longer masks
+  as a silent "stuck on acknowledge screen". Relay PR (fix/pair-aes-gcm-rc12)
+  is the canonical fix for the issue reported in #79.
+
 ## [3.3.1-rc.11] — 2026-04-23
 
 OpenClaw-side universal pair reachability — the plugin's `totalreclaw_pair` tool now routes through the relay WebSocket by default, mirroring the Python `2.3.1rc10` pivot on the Hermes side. The URL returned to the user is `https://api-staging.totalreclaw.xyz/pair/p/<token>#pk=<gateway_pubkey>` instead of the previous `http://<gateway-host>:<port>/plugin/totalreclaw/pair/finish?sid=<sid>#pk=…`. Managed hosts, Docker-in-cloud setups, phone-scan-QR flows, and split-network operators can now complete pairing without the browser needing loopback or LAN access to the gateway.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.3.1-rc.11",
+  "version": "3.3.1-rc.13",
   "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": [

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

package/pair-remote-client.ts

@@ -7,7 +7,7 @@
  * Python implementation byte-for-byte so either side can open a session that
  * the relay (`totalreclaw-relay`) + browser page (`pair-html.ts`) already
  * understand. Crypto primitives come from the shared ``pair-crypto.ts``
- * module — the same ECDH + HKDF + ChaCha20-Poly1305 stack the loopback HTTP
+ * module — the same ECDH + HKDF + AES-256-GCM stack the loopback HTTP
  * server uses.
  *
  * Flow (this file implements the gateway half):