keyvoid 1.0.0

package/src/engine/suppressor/helpers/macos-pynput-helper.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+macOS Keyboard Suppressor using pynput (preferred method).
+
+Uses pynput's suppress=True which blocks ALL keys at the system level,
+including function keys, media keys (volume, brightness), and modifiers.
+
+Output protocol (stdout):
+  STARTED           — helper is active and blocking keys
+  K:<keycode>:<1|0> — key event (1=down, 0=up)
+  FAILSAFE          — Esc+Space held for 5 seconds
+
+Requires: pip3 install pynput
+"""
+
+import sys
+import time
+import signal
+import threading
+
+try:
+    from pynput import keyboard
+except ImportError:
+    print("ERROR: pynput not installed. Run: pip3 install pynput", file=sys.stderr, flush=True)
+    sys.exit(2)  # Exit code 2 = missing dependency
+
+# ── State for failsafe detection ──
+esc_pressed = False
+space_pressed = False
+failsafe_start = None
+FAILSAFE_SECONDS = 5.0
+lock = threading.Lock()
+
+
+def get_keycode(key):
+    """Extract a numeric keycode from a pynput key object."""
+    # Try to get the virtual key code
+    if hasattr(key, 'vk') and key.vk is not None:
+        return key.vk
+    # Try scan code
+    if hasattr(key, 'value') and hasattr(key.value, 'vk'):
+        return key.value.vk
+    # Known special keys → macOS keycodes
+    key_map = {
+        keyboard.Key.esc: 53,
+        keyboard.Key.space: 49,
+        keyboard.Key.tab: 48,
+        keyboard.Key.caps_lock: 57,
+        keyboard.Key.shift: 56,
+        keyboard.Key.shift_r: 60,
+        keyboard.Key.ctrl: 59,
+        keyboard.Key.ctrl_r: 62,
+        keyboard.Key.alt: 58,
+        keyboard.Key.alt_r: 61,
+        keyboard.Key.cmd: 55,
+        keyboard.Key.cmd_r: 54,
+        keyboard.Key.enter: 36,
+        keyboard.Key.backspace: 51,
+        keyboard.Key.delete: 117,
+        keyboard.Key.up: 126,
+        keyboard.Key.down: 125,
+        keyboard.Key.left: 123,
+        keyboard.Key.right: 124,
+        keyboard.Key.home: 115,
+        keyboard.Key.end: 119,
+        keyboard.Key.page_up: 116,
+        keyboard.Key.page_down: 121,
+        keyboard.Key.f1: 122,
+        keyboard.Key.f2: 120,
+        keyboard.Key.f3: 99,
+        keyboard.Key.f4: 118,
+        keyboard.Key.f5: 96,
+        keyboard.Key.f6: 97,
+        keyboard.Key.f7: 98,
+        keyboard.Key.f8: 100,
+        keyboard.Key.f9: 101,
+        keyboard.Key.f10: 109,
+        keyboard.Key.f11: 103,
+        keyboard.Key.f12: 111,
+        keyboard.Key.media_play_pause: 1000,
+        keyboard.Key.media_next: 1001,
+        keyboard.Key.media_previous: 1002,
+        keyboard.Key.media_volume_up: 1003,
+        keyboard.Key.media_volume_down: 1004,
+        keyboard.Key.media_volume_mute: 1005,
+    }
+    return key_map.get(key, 0)
+
+
+def is_esc(key):
+    """Check if the key is Escape."""
+    return key == keyboard.Key.esc
+
+
+def is_space(key):
+    """Check if the key is Space."""
+    return key == keyboard.Key.space
+
+
+def check_failsafe():
+    """Background thread that monitors the failsafe combo timing."""
+    global failsafe_start
+    while True:
+        time.sleep(0.1)
+        with lock:
+            if esc_pressed and space_pressed:
+                if failsafe_start is None:
+                    failsafe_start = time.time()
+                elif time.time() - failsafe_start >= FAILSAFE_SECONDS:
+                    print("FAILSAFE", flush=True)
+                    # Give Node.js a moment to read the output
+                    time.sleep(0.1)
+                    import os
+                    os._exit(0)
+            else:
+                failsafe_start = None
+
+
+def on_press(key):
+    """Called on every key press. Returns nothing to suppress the key."""
+    global esc_pressed, space_pressed
+
+    keycode = get_keycode(key)
+    print(f"K:{keycode}:1", flush=True)
+
+    with lock:
+        if is_esc(key):
+            esc_pressed = True
+        if is_space(key):
+            space_pressed = True
+
+    # Returning None with suppress=True blocks the key
+    return None
+
+
+def on_release(key):
+    """Called on every key release."""
+    global esc_pressed, space_pressed, failsafe_start
+
+    keycode = get_keycode(key)
+    print(f"K:{keycode}:0", flush=True)
+
+    with lock:
+        if is_esc(key):
+            esc_pressed = False
+        if is_space(key):
+            space_pressed = False
+
+    return None
+
+
+def cleanup(sig=None, frame=None):
+    """Clean exit on signal."""
+    import os
+    os._exit(0)
+
+
+# ── Signal handlers ──
+signal.signal(signal.SIGTERM, cleanup)
+signal.signal(signal.SIGINT, cleanup)
+
+# ── Start failsafe monitor thread ──
+failsafe_thread = threading.Thread(target=check_failsafe, daemon=True)
+failsafe_thread.start()
+
+# ── Start the listener ──
+# suppress=True is the key: it blocks ALL keyboard input from reaching
+# other applications, including function keys, media keys, and modifiers.
+try:
+    with keyboard.Listener(
+        on_press=on_press,
+        on_release=on_release,
+        suppress=True
+    ) as listener:
+        print("STARTED", flush=True)
+        listener.join()
+except Exception as e:
+    print(f"ERROR: {e}", file=sys.stderr, flush=True)
+    sys.exit(1)

package/src/engine/suppressor/helpers/windows-helper.ps1

@@ -0,0 +1,144 @@
+# ─── Windows Keyboard Suppressor ──────────────────────────────────────
+# Uses SetWindowsHookEx with WH_KEYBOARD_LL to intercept and block
+# all keyboard input at the system level.
+#
+# Output protocol (stdout):
+#   STARTED           — helper is active and blocking keys
+#   K:<keycode>:<1|0> — key event (1=down, 0=up)
+#   FAILSAFE          — Esc+Space held for 5 seconds
+
+Add-Type -TypeDefinition @"
+using System;
+using System.Diagnostics;
+using System.Runtime.InteropServices;
+using System.Threading;
+
+public class KeyVoidBlocker {
+    private const int WH_KEYBOARD_LL = 13;
+    private const int WM_KEYDOWN = 0x0100;
+    private const int WM_KEYUP = 0x0101;
+    private const int WM_SYSKEYDOWN = 0x0104;
+    private const int WM_SYSKEYUP = 0x0105;
+    private const int VK_ESCAPE = 0x1B;
+    private const int VK_SPACE = 0x20;
+
+    private delegate IntPtr LowLevelKeyboardProc(int nCode, IntPtr wParam, IntPtr lParam);
+
+    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
+    private static extern IntPtr SetWindowsHookEx(int idHook, LowLevelKeyboardProc lpfn, IntPtr hMod, uint dwThreadId);
+
+    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool UnhookWindowsHookEx(IntPtr hhk);
+
+    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
+    private static extern IntPtr CallNextHookEx(IntPtr hhk, int nCode, IntPtr wParam, IntPtr lParam);
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Auto, SetLastError = true)]
+    private static extern IntPtr GetModuleHandle(string lpModuleName);
+
+    [DllImport("user32.dll")]
+    private static extern bool GetMessage(out MSG lpMsg, IntPtr hWnd, uint wMsgFilterMin, uint wMsgFilterMax);
+
+    [DllImport("user32.dll")]
+    private static extern bool TranslateMessage(ref MSG lpMsg);
+
+    [DllImport("user32.dll")]
+    private static extern IntPtr DispatchMessage(ref MSG lpMsg);
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct MSG {
+        public IntPtr hwnd;
+        public uint message;
+        public IntPtr wParam;
+        public IntPtr lParam;
+        public uint time;
+        public POINT pt;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct POINT {
+        public int x;
+        public int y;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct KBDLLHOOKSTRUCT {
+        public int vkCode;
+        public int scanCode;
+        public int flags;
+        public int time;
+        public IntPtr dwExtraInfo;
+    }
+
+    private static IntPtr hookId = IntPtr.Zero;
+    private static bool escPressed = false;
+    private static bool spacePressed = false;
+    private static DateTime? failsafeStart = null;
+
+    private static IntPtr HookCallback(int nCode, IntPtr wParam, IntPtr lParam) {
+        if (nCode >= 0) {
+            KBDLLHOOKSTRUCT hookStruct = Marshal.PtrToStructure<KBDLLHOOKSTRUCT>(lParam);
+            int vkCode = hookStruct.vkCode;
+            bool isDown = (wParam == (IntPtr)WM_KEYDOWN || wParam == (IntPtr)WM_SYSKEYDOWN);
+
+            Console.WriteLine("K:" + vkCode + ":" + (isDown ? "1" : "0"));
+            Console.Out.Flush();
+
+            // Failsafe tracking
+            if (isDown) {
+                if (vkCode == VK_ESCAPE) escPressed = true;
+                if (vkCode == VK_SPACE) spacePressed = true;
+            } else {
+                if (vkCode == VK_ESCAPE) escPressed = false;
+                if (vkCode == VK_SPACE) spacePressed = false;
+            }
+
+            if (escPressed && spacePressed) {
+                if (!failsafeStart.HasValue) {
+                    failsafeStart = DateTime.Now;
+                } else if ((DateTime.Now - failsafeStart.Value).TotalSeconds >= 5) {
+                    Console.WriteLine("FAILSAFE");
+                    Console.Out.Flush();
+                    UnhookWindowsHookEx(hookId);
+                    Environment.Exit(0);
+                }
+            } else {
+                failsafeStart = null;
+            }
+
+            // Block the key by returning 1
+            return (IntPtr)1;
+        }
+        return CallNextHookEx(hookId, nCode, wParam, lParam);
+    }
+
+    public static void Run() {
+        LowLevelKeyboardProc proc = HookCallback;
+        using (Process curProcess = Process.GetCurrentProcess())
+        using (ProcessModule curModule = curProcess.MainModule) {
+            hookId = SetWindowsHookEx(WH_KEYBOARD_LL, proc,
+                GetModuleHandle(curModule.ModuleName), 0);
+        }
+
+        if (hookId == IntPtr.Zero) {
+            Console.Error.WriteLine("ERROR: Failed to set keyboard hook");
+            Environment.Exit(1);
+        }
+
+        Console.WriteLine("STARTED");
+        Console.Out.Flush();
+
+        // Message loop (required for the hook to work)
+        MSG msg;
+        while (GetMessage(out msg, IntPtr.Zero, 0, 0)) {
+            TranslateMessage(ref msg);
+            DispatchMessage(ref msg);
+        }
+
+        UnhookWindowsHookEx(hookId);
+    }
+}
+"@ -ReferencedAssemblies System.Runtime.InteropServices
+
+[KeyVoidBlocker]::Run()

package/src/engine/suppressor/index.js

@@ -0,0 +1,306 @@
+// ─── Keyboard Suppressor ─────────────────────────────────────────────
+// Manages platform-specific native helpers that actually block keyboard
+// input at the system level. Communicates via child process stdout.
+
+import { spawn, execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import { EventEmitter } from 'events';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const HELPERS_DIR = join(__dirname, 'helpers');
+
+export class KeyboardSuppressor extends EventEmitter {
+  constructor() {
+    super();
+    this.process = null;
+    this.running = false;
+    this.keyCount = 0;
+    this.escPressed = false;
+    this.spacePressed = false;
+    this.failsafeStart = null;
+    this.failsafeTimeout = 5000; // 5 seconds
+    this.failsafeTimer = null;
+
+    // Guarantee the blocker process is killed even on hard crashes
+    process.on('exit', () => {
+      if (this.process) {
+        try { this.process.kill('SIGKILL'); } catch (e) {}
+      }
+    });
+  }
+
+  async start() {
+    const platform = process.platform;
+
+    try {
+      switch (platform) {
+        case 'darwin':
+          await this._startMacOS();
+          break;
+        case 'win32':
+          await this._startWindows();
+          break;
+        case 'linux':
+          await this._startLinux();
+          break;
+        default:
+          throw new Error(`Unsupported platform: ${platform}`);
+      }
+    } catch (err) {
+      this.emit('error', err);
+      return false;
+    }
+
+    return true;
+  }
+
+  stop() {
+    if (this.failsafeTimer) {
+      clearInterval(this.failsafeTimer);
+      this.failsafeTimer = null;
+    }
+
+    if (this.process) {
+      const p = this.process;
+      try {
+        // Use SIGKILL synchronously. If this runs inside a process.on('exit')
+        // event, setTimeouts won't execute. We must ensure immediate death 
+        // to release the OS level keyboard hooks.
+        p.kill('SIGKILL');
+      } catch {
+        // Process may have already exited
+      }
+      this.process = null;
+    }
+    this.running = false;
+
+    // Platform-specific cleanup
+    if (process.platform === 'linux') {
+      this._cleanupLinux();
+    }
+  }
+
+  async _startMacOS() {
+    // Strategy: try pynput (blocks ALL keys including media/fn),
+    // then fall back to Swift CGEventTap helper.
+
+    // 1. Try pynput-based helper (preferred — proven to block function/media keys)
+    const pynputHelper = join(HELPERS_DIR, 'macos-pynput-helper.py');
+    if (existsSync(pynputHelper)) {
+      const pythonExe = await this._getPythonWithPynput();
+      if (pythonExe) {
+        this.process = spawn(pythonExe, [pynputHelper], {
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this._bindProcess();
+        return;
+      }
+    }
+
+    // 2. Fall back to Swift CGEventTap helper
+    const helperSrc = join(HELPERS_DIR, 'macos-helper.swift');
+    if (!existsSync(helperSrc)) {
+      throw new Error('No macOS helper found. Install pynput (python3 -m venv .venv && source .venv/bin/activate && pip install pynput) or ensure Swift is available.');
+    }
+
+    // Compile the Swift helper to a cached binary for fast subsequent runs
+    const cacheDir = join(process.env.HOME || '/tmp', '.keyvoid-cache');
+    const helperBin = join(cacheDir, 'keyvoid-macos-helper');
+
+    // Invalidate cache if source is newer than binary
+    if (existsSync(helperBin)) {
+      try {
+        const { statSync } = await import('fs');
+        const srcStat = statSync(helperSrc);
+        const binStat = statSync(helperBin);
+        if (srcStat.mtimeMs > binStat.mtimeMs) {
+          execSync(`rm -f "${helperBin}"`, { stdio: 'pipe' });
+        }
+      } catch {
+        // Ignore stat errors
+      }
+    }
+
+    if (!existsSync(helperBin)) {
+      try {
+        execSync(`mkdir -p ${cacheDir}`, { stdio: 'pipe' });
+        execSync(`swiftc -O "${helperSrc}" -o "${helperBin}"`, {
+          stdio: 'pipe',
+          timeout: 30000, // 30s compile timeout
+        });
+      } catch {
+        // Fallback: run Swift as a script (slower startup)
+        this.process = spawn('swift', [helperSrc], { stdio: ['pipe', 'pipe', 'pipe'] });
+        this._bindProcess();
+        return;
+      }
+    }
+
+    this.process = spawn(helperBin, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+    this._bindProcess();
+  }
+
+  // Find python executable with pynput installed
+  async _getPythonWithPynput() {
+    // Check bundled venv first
+    const venvPython = join(__dirname, '../../../.venv/bin/python3');
+    if (existsSync(venvPython)) {
+      try {
+        execSync(`"${venvPython}" -c "from pynput import keyboard"`, { stdio: 'pipe' });
+        return venvPython;
+      } catch (e) {}
+    }
+
+    // Check global python3
+    try {
+      execSync('python3 -c "from pynput import keyboard"', {
+        stdio: 'pipe',
+        timeout: 5000,
+      });
+      return 'python3';
+    } catch {
+      return null;
+    }
+  }
+
+  async _startWindows() {
+    const helperScript = join(HELPERS_DIR, 'windows-helper.ps1');
+
+    if (!existsSync(helperScript)) {
+      throw new Error('Windows helper script not found');
+    }
+
+    this.process = spawn('powershell', [
+      '-ExecutionPolicy', 'Bypass',
+      '-File', helperScript,
+    ], { stdio: ['pipe', 'pipe', 'pipe'] });
+
+    this._bindProcess();
+  }
+
+  async _startLinux() {
+    const helperScript = join(HELPERS_DIR, 'linux-helper.py');
+
+    if (!existsSync(helperScript)) {
+      throw new Error('Linux helper script not found');
+    }
+
+    this.process = spawn('python3', [helperScript], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    this._bindProcess();
+  }
+
+  _bindProcess() {
+    const proc = this.process;
+
+    proc.stdout.on('data', (data) => {
+      const lines = data.toString().split('\n').filter(l => l.trim());
+
+      for (const line of lines) {
+        if (line === 'STARTED') {
+          this.running = true;
+          this.emit('started');
+          continue;
+        }
+
+        if (line === 'FAILSAFE') {
+          this.emit('failsafe');
+          continue;
+        }
+
+        if (line.startsWith('K:')) {
+          // Format: K:<keycode>:<down|up>
+          const parts = line.split(':');
+          const keycode = parseInt(parts[1], 10);
+          const isDown = parts[2] === '1';
+
+          this.keyCount++;
+          this.emit('key', { keycode, isDown, count: this.keyCount });
+
+          // Track failsafe combo (Esc + Space held for 5s)
+          this._trackFailsafe(keycode, isDown);
+        }
+      }
+    });
+
+    proc.stderr.on('data', (data) => {
+      const msg = data.toString().trim();
+      if (msg.includes('Accessibility') || msg.includes('ERROR')) {
+        this.emit('permission-error', msg);
+      }
+    });
+
+    proc.on('close', (code) => {
+      this.running = false;
+      this.emit('close', code);
+    });
+
+    proc.on('error', (err) => {
+      this.running = false;
+      this.emit('error', err);
+    });
+  }
+
+  _trackFailsafe(keycode, isDown) {
+    // macOS keycodes: Esc = 53, Space = 49
+    // Windows virtual keycodes: Esc = 27, Space = 32
+    // We handle both sets
+    const isEsc = keycode === 53 || keycode === 27 || keycode === 1;
+    const isSpace = keycode === 49 || keycode === 32 || keycode === 57;
+
+    if (isDown) {
+      if (isEsc) this.escPressed = true;
+      if (isSpace) this.spacePressed = true;
+    } else {
+      if (isEsc) this.escPressed = false;
+      if (isSpace) this.spacePressed = false;
+    }
+
+    if (this.escPressed && this.spacePressed) {
+      if (!this.failsafeStart) {
+        this.failsafeStart = Date.now();
+        this.emit('failsafe-progress', 0);
+        this.failsafeTimer = setInterval(() => {
+          if (!this.escPressed || !this.spacePressed) {
+            this.failsafeStart = null;
+            clearInterval(this.failsafeTimer);
+            this.failsafeTimer = null;
+            this.emit('failsafe-cancel');
+            return;
+          }
+          const elapsed = Date.now() - this.failsafeStart;
+          const progress = Math.min(1, elapsed / this.failsafeTimeout);
+          this.emit('failsafe-progress', progress);
+          if (progress >= 1) {
+            this.emit('failsafe');
+            clearInterval(this.failsafeTimer);
+            this.failsafeTimer = null;
+          }
+        }, 100);
+      }
+    } else {
+      if (this.failsafeStart) {
+        this.failsafeStart = null;
+        if (this.failsafeTimer) {
+          clearInterval(this.failsafeTimer);
+          this.failsafeTimer = null;
+        }
+        this.emit('failsafe-cancel');
+      }
+    }
+  }
+
+  _cleanupLinux() {
+    // Re-enable any disabled keyboard devices
+    try {
+      execSync('python3 -c "import subprocess; subprocess.run([\'xinput\', \'--list\', \'--id-only\'])"', { stdio: 'pipe' });
+    } catch {
+      // Best effort cleanup
+    }
+  }
+}

package/src/scripts/postinstall.js

@@ -0,0 +1,33 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, '../../');
+
+if (process.platform === 'darwin') {
+  const venvPath = join(rootDir, '.venv');
+  if (!existsSync(venvPath)) {
+    console.log('[KeyVoid] 🍏 Setting up isolated Python environment for macOS (pynput)...');
+    try {
+      // Create virtual environment
+      execSync('python3 -m venv .venv', { cwd: rootDir, stdio: 'inherit' });
+      
+      // Install pynput inside venv
+      // Using bash to source the activate script
+      execSync('source .venv/bin/activate && pip install pynput', { 
+        cwd: rootDir, 
+        stdio: 'inherit',
+        shell: '/bin/bash'
+      });
+      
+      console.log('✅ macOS Python dependencies installed (pynput). Media keys will be suppressed.');
+    } catch (err) {
+      console.error('⚠️ Failed to install pynput via venv. KeyVoid will gracefully fall back to the Swift CGEventTap helper (some media keys may not be suppressed).');
+    }
+  } else {
+    console.log('[KeyVoid] 🍏 macOS Python environment (.venv) already exists.');
+  }
+}