feat(humanize): implement CDP Isolated Worlds and trusted keyboard events (fixes #110)

js/src/human/keyboard.ts

@@ -1,8 +1,12 @@
 /**
  * cloakbrowser-human — Human-like keyboard input.
+ *
+ * Stealth-aware: when a CDPSession is provided, shift symbols are typed
+ * via CDP Input.dispatchKeyEvent (isTrusted=true, no evaluate stack trace).
+ * Falls back to page.evaluate when no CDPSession is available.
  */
 
-import type { Page } from 'playwright-core';
+import type { Page, CDPSession } from 'playwright-core';
 import { RawKeyboard } from './mouse.js';
 import { HumanConfig, rand, randRange, sleep } from './config.js';
 
@@ -22,6 +26,31 @@ const NEARBY_KEYS: Record<string, string> = {
   '6': '57ty', '7': '68yu', '8': '79ui', '9': '80io', '0': '9p',
 };
 
+/**
+ * CDP key code for each shift symbol's physical key.
+ * Used by Input.dispatchKeyEvent to produce isTrusted=true events.
+ */
+const SHIFT_SYMBOL_CODES: Record<string, string> = {
+  '!': 'Digit1', '@': 'Digit2', '#': 'Digit3', '$': 'Digit4',
+  '%': 'Digit5', '^': 'Digit6', '&': 'Digit7', '*': 'Digit8',
+  '(': 'Digit9', ')': 'Digit0', '_': 'Minus', '+': 'Equal',
+  '{': 'BracketLeft', '}': 'BracketRight', '|': 'Backslash',
+  ':': 'Semicolon', '"': 'Quote', '<': 'Comma', '>': 'Period',
+  '?': 'Slash', '~': 'Backquote',
+};
+
+/**
+ * Windows virtual key codes for shift symbols.
+ * Input.dispatchKeyEvent uses these to match real keyboard behavior.
+ */
+const SHIFT_SYMBOL_KEYCODES: Record<string, number> = {
+  '!': 49, '@': 50, '#': 51, '$': 52, '%': 53,
+  '^': 54, '&': 55, '*': 56, '(': 57, ')': 48,
+  '_': 189, '+': 187, '{': 219, '}': 221, '|': 220,
+  ':': 186, '"': 222, '<': 188, '>': 190, '?': 191,
+  '~': 192,
+};
+
 function isAscii(ch: string): boolean {
   const code = ch.codePointAt(0);
   return code !== undefined && code < 128;
@@ -37,11 +66,24 @@ function getNearbyKey(ch: string): string {
   return ch;
 }
 
+function isUpperCase(ch: string): boolean {
+  return ch.length === 1 && ch >= 'A' && ch <= 'Z';
+}
+
+/**
+ * Type text with human-like per-character timing, mistype simulation,
+ * and realistic shift handling.
+ *
+ * @param cdpSession - If provided, shift symbols use CDP Input.dispatchKeyEvent
+ *   producing isTrusted=true events with no evaluate stack trace.
+ *   If null/undefined, falls back to page.evaluate (detectable).
+ */
 export async function humanType(
   page: Page,
   raw: RawKeyboard,
   text: string,
   cfg: HumanConfig,
+  cdpSession?: CDPSession | null,
 ): Promise<void> {
   const chars = [...text]; // Handle emoji surrogate pairs correctly
 
@@ -72,7 +114,7 @@ export async function humanType(
     if (isUpperCase(ch)) {
       await typeShiftedChar(raw, ch, cfg);
     } else if (SHIFT_SYMBOLS.has(ch)) {
-      await typeShiftSymbol(page, raw, ch, cfg);
+      await typeShiftSymbol(page, raw, ch, cfg, cdpSession);
     } else {
       await typeNormalChar(raw, ch, cfg);
     }
@@ -99,23 +141,67 @@ async function typeShiftedChar(raw: RawKeyboard, ch: string, cfg: HumanConfig):
   await raw.up('Shift');
 }
 
-async function typeShiftSymbol(page: Page, raw: RawKeyboard, ch: string, cfg: HumanConfig): Promise<void> {
-  await raw.down('Shift');
-  await sleep(randRange(cfg.shift_down_delay));
-  await raw.insertText(ch);
-  await page.evaluate((key: string) => {
-    const el = document.activeElement;
-    if (el) {
-      el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
-      el.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
-    }
-  }, ch);
-  await sleep(randRange(cfg.shift_up_delay));
-  await raw.up('Shift');
-}
+/**
+ * Type a shift symbol character.
+ *
+ * Stealth path (cdpSession provided):
+ *   Uses CDP Input.dispatchKeyEvent → isTrusted=true, clean stack.
+ *
+ * Fallback path (no cdpSession):
+ *   Uses raw.insertText + page.evaluate to dispatch synthetic KeyboardEvent.
+ *   Detectable via isTrusted=false and evaluate stack frame.
+ */
+async function typeShiftSymbol(
+  page: Page,
+  raw: RawKeyboard,
+  ch: string,
+  cfg: HumanConfig,
+  cdpSession?: CDPSession | null,
+): Promise<void> {
+  if (cdpSession) {
+    // --- Stealth path: CDP Input.dispatchKeyEvent ---
+    const code = SHIFT_SYMBOL_CODES[ch] || '';
+    const keyCode = SHIFT_SYMBOL_KEYCODES[ch] || 0;
 
-function isUpperCase(ch: string): boolean {
-  return ch.length === 1 && ch >= 'A' && ch <= 'Z';
+    await raw.down('Shift');
+    await sleep(randRange(cfg.shift_down_delay));
+
+    await cdpSession.send('Input.dispatchKeyEvent', {
+      type: 'keyDown',
+      modifiers: 8, // Shift modifier flag
+      key: ch,
+      code,
+      windowsVirtualKeyCode: keyCode,
+      text: ch,
+      unmodifiedText: ch,
+    });
+    await sleep(randRange(cfg.key_hold));
+
+    await cdpSession.send('Input.dispatchKeyEvent', {
+      type: 'keyUp',
+      modifiers: 8,
+      key: ch,
+      code,
+      windowsVirtualKeyCode: keyCode,
+    });
+
+    await sleep(randRange(cfg.shift_up_delay));
+    await raw.up('Shift');
+  } else {
+    // --- Fallback path: page.evaluate (detectable) ---
+    await raw.down('Shift');
+    await sleep(randRange(cfg.shift_down_delay));
+    await raw.insertText(ch);
+    await page.evaluate((key: string) => {
+      const el = document.activeElement;
+      if (el) {
+        el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
+        el.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
+      }
+    }, ch);
+    await sleep(randRange(cfg.shift_up_delay));
+    await raw.up('Shift');
+  }
 }
 
 async function interCharDelay(cfg: HumanConfig): Promise<void> {