@totalreclaw/totalreclaw 3.3.1-rc.2 → 3.3.1-rc.21

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

package/pair-qr.ts

@@ -0,0 +1,152 @@
+/**
+ * pair-qr — QR encoders for the rc.5 pair-tool payload.
+ *
+ * Two helpers that render the pair URL as either a PNG (for
+ * image-capable chat transports like Telegram) or a Unicode block
+ * string (for terminal-only transports like the OpenClaw native CLI).
+ *
+ * Phrase-safety invariant (see
+ * `project_phrase_safety_rule.md` in the internal repo):
+ *   The QR payload is ONLY the pair URL. The 6-digit PIN is a separate
+ *   out-of-band confirmation — it is NEVER baked into the QR. The URL
+ *   itself carries only the session token + gateway ephemeral pubkey
+ *   (fragment-encoded).
+ *
+ * Size profile for a typical ~110-char pair URL:
+ *   - `encodePng` defaults (scale=10, margin=4): ~4 KiB PNG, ~5.5 KiB
+ *     base64. Fits comfortably in a tool-call response.
+ *   - `encodeUnicode` (margin=2): ~1.1 KiB, 23 lines.
+ *
+ * We wrap the `qrcode` npm package (~50 KiB, pure TS, no native
+ * bindings) so neither tsx dev runs nor the published plugin depend on
+ * the bundler understanding CJS vs ESM subpath imports. All we use is
+ * the high-level `toBuffer` / `toString` surface.
+ */
+
+// Lazy import shape — avoids pulling `qrcode` into module load when the
+// tool is never invoked. The `qrcode` types ship with the package but
+// we describe the tiny surface we use here so a future type-drift in
+// upstream doesn't break the build.
+type QrCodeModule = {
+  toBuffer(
+    text: string,
+    options?: { errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; scale?: number; margin?: number },
+  ): Promise<Buffer>;
+  toString(
+    text: string,
+    options?: { type?: 'utf8'; errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; margin?: number },
+  ): Promise<string>;
+};
+
+/**
+ * Error class raised by the rc.5 QR encoders.
+ *
+ * Extends the built-in `Error` so `instanceof Error` checks in callers
+ * keep working.
+ */
+export class QREncodeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'QREncodeError';
+  }
+}
+
+// QR v40 maxes out at ~2953 alphanumeric bytes at ECC-L. We reject
+// payloads over 2 KiB — the pair URL should never approach this. This
+// is defence-in-depth against a caller accidentally feeding a
+// phrase-length blob.
+const MAX_PAYLOAD_BYTES = 2048;
+
+function validatePayload(url: unknown): asserts url is string {
+  if (typeof url !== 'string') {
+    throw new QREncodeError(`url must be a string, got ${typeof url}`);
+  }
+  if (url.length === 0) {
+    throw new QREncodeError('url must not be empty');
+  }
+  const bytes = Buffer.byteLength(url, 'utf-8');
+  if (bytes > MAX_PAYLOAD_BYTES) {
+    throw new QREncodeError(
+      `url too large for QR encoding: ${bytes} bytes (max ${MAX_PAYLOAD_BYTES}). ` +
+        'This limit prevents accidentally encoding phrase-length blobs; a pair ' +
+        'URL should be ~80-150 bytes.',
+    );
+  }
+}
+
+async function loadQrCodeModule(): Promise<QrCodeModule> {
+  const raw = (await import('qrcode' as string)) as unknown as
+    | (QrCodeModule & { default?: QrCodeModule })
+    | { default: QrCodeModule };
+  // qrcode ships CJS; the `default` export contains the surface under
+  // both Node's ESM interop and tsx's loader.
+  const mod = (raw as { default?: QrCodeModule }).default ?? (raw as QrCodeModule);
+  return mod;
+}
+
+export interface EncodePngOptions {
+  /** Error-correction level. Defaults to `'M'` (15%). */
+  ecc?: 'L' | 'M' | 'Q' | 'H';
+  /** Pixels per module. Defaults to 10 → ~300x300 px image. */
+  boxSize?: number;
+  /** Quiet-zone width in modules. Defaults to 4 (QR standard minimum). */
+  border?: number;
+}
+
+export interface EncodeUnicodeOptions {
+  /** Error-correction level. Defaults to `'M'`. */
+  ecc?: 'L' | 'M' | 'Q' | 'H';
+  /** Quiet-zone width in modules. Defaults to 2. */
+  border?: number;
+}
+
+/**
+ * Render `url` as a PNG QR code.
+ *
+ * @throws {QREncodeError} if the URL is empty, non-string, or exceeds
+ *   the 2 KiB safety cap.
+ */
+export async function encodePng(
+  url: string,
+  options: EncodePngOptions = {},
+): Promise<Buffer> {
+  validatePayload(url);
+  const qr = await loadQrCodeModule();
+  try {
+    return await qr.toBuffer(url, {
+      errorCorrectionLevel: options.ecc ?? 'M',
+      scale: Math.max(1, options.boxSize ?? 10),
+      margin: Math.max(0, options.border ?? 4),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new QREncodeError(`QR encoding failed: ${msg}`);
+  }
+}
+
+/**
+ * Render `url` as a Unicode block QR string (for terminal output).
+ *
+ * Uses half-block glyphs so each character represents two vertical
+ * pixels — the resulting string renders square-ish in terminals with
+ * ~2:1 line-height. Emitted as a single newline-delimited string.
+ *
+ * @throws {QREncodeError} on invalid input.
+ */
+export async function encodeUnicode(
+  url: string,
+  options: EncodeUnicodeOptions = {},
+): Promise<string> {
+  validatePayload(url);
+  const qr = await loadQrCodeModule();
+  try {
+    return await qr.toString(url, {
+      type: 'utf8',
+      errorCorrectionLevel: options.ecc ?? 'M',
+      margin: Math.max(0, options.border ?? 2),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new QREncodeError(`QR encoding failed: ${msg}`);
+  }
+}