keyvoid 1.0.0

package/src/app.js

@@ -0,0 +1,294 @@
+// ─── KeyVoid Application ─────────────────────────────────────────────
+// Main orchestrator: ties together the engine, renderer, mouse,
+// and skins into a cohesive full-screen keyboard locking application.
+
+import { Renderer } from './ui/renderer.js';
+import { MouseTracker } from './ui/mouse.js';
+import { KeyboardSuppressor } from './engine/suppressor/index.js';
+import { checkPermissions } from './engine/permissions.js';
+import { renderClean } from './ui/skins/clean.js';
+import { renderToddler } from './ui/skins/toddler.js';
+import { renderCat } from './ui/skins/cat.js';
+import { renderPrank, checkPrankExit, resetPrankState } from './ui/skins/prank.js';
+import { renderHacker } from './ui/skins/hacker.js';
+import { renderArcade } from './ui/skins/arcade.js';
+import { renderZen } from './ui/skins/zen.js';
+import { renderUnlockSequence } from './ui/unlock-sequence.js';
+import { write } from './utils/terminal.js';
+import { RESET } from './utils/colors.js';
+import chalk from 'chalk';
+
+export class KeyVoidApp {
+  constructor(options = {}) {
+    this.skin = options.skin || 'clean';
+    this.renderer = new Renderer();
+    this.mouse = new MouseTracker();
+    this.suppressor = new KeyboardSuppressor();
+
+    this.state = {
+      keyCount: 0,
+      startTime: Date.now(),
+      suppressorActive: false,
+      failsafeProgress: 0,
+      skinName: this.skin,
+      unlocking: false,
+      unlockTick: 0
+    };
+
+    this.tick = 0;
+    this.running = false;
+    this._boundCleanup = this._cleanup.bind(this);
+  }
+
+  async start() {
+    // ── Permission Check ──
+    const perms = checkPermissions();
+    if (!perms.ok) {
+      console.log(perms.guide);
+      console.log(chalk.red.bold('\n  Cannot start KeyVoid without required permissions.\n'));
+      process.exit(1);
+    }
+
+    // ── Show splash ──
+    this._showSplash();
+
+    // ── Setup terminal ──
+    this.renderer.setup();
+    this.running = true;
+
+    // ── Register cleanup handlers ──
+    process.on('SIGINT', this._boundCleanup);
+    process.on('SIGTERM', this._boundCleanup);
+    process.on('uncaughtException', (err) => {
+      this._cleanup();
+      console.error('Fatal error:', err);
+      process.exit(1);
+    });
+    process.on('exit', () => {
+      // Last-resort cleanup
+      if (this.running) {
+        this.suppressor.stop();
+      }
+    });
+
+    // ── Setup mouse tracking ──
+    this.mouse.start();
+    this._setupMouseRegions();
+
+    // ── Start keyboard suppressor ──
+    this.suppressor.on('started', () => {
+      this.state.suppressorActive = true;
+    });
+
+    this.suppressor.on('key', ({ keycode, isDown, count }) => {
+      this.state.keyCount = count;
+      
+      // Track spacebar for the Arcade game over screen (Hold 3 sec to restart)
+      if (keycode === 49 || keycode === 32 || keycode === 57) {
+        this.state.isSpaceDown = isDown;
+      }
+      
+      if (isDown) {
+        this.state.lastKeyCode = keycode;
+      }
+    });
+
+    this.suppressor.on('failsafe-progress', (progress) => {
+      this.state.failsafeProgress = progress;
+    });
+
+    this.suppressor.on('failsafe-cancel', () => {
+      this.state.failsafeProgress = 0;
+    });
+
+    this.suppressor.on('failsafe', () => {
+      this._cleanup();
+      console.log(chalk.yellow('\n  ⚡ Failsafe triggered! Keyboard unlocked.\n'));
+      process.exit(0);
+    });
+
+    this.suppressor.on('permission-error', (msg) => {
+      this._cleanup();
+      console.log(chalk.red(`\n  ❌ Permission error: ${msg}`));
+      console.log(chalk.yellow('  Please grant Accessibility permission and try again.\n'));
+      process.exit(1);
+    });
+
+    this.suppressor.on('error', (err) => {
+      // Non-fatal: continue with UI but mark suppressor as inactive
+      this.state.suppressorActive = false;
+    });
+
+    this.suppressor.on('close', (code) => {
+      this.state.suppressorActive = false;
+      // If the suppressor closes unexpectedly, keep the UI running
+      // (allows for demo mode where suppressor isn't available)
+    });
+
+    // Start the suppressor
+    const suppressorStarted = await this.suppressor.start();
+    if (!suppressorStarted) {
+      // Run in demo mode (UI only, no actual key blocking)
+      this.state.suppressorActive = false;
+    }
+
+    // ── Setup render function ──
+    this.renderer.setRenderFunction((cols, rows) => {
+      return this._render(cols, rows);
+    });
+
+    // ── Handle stdin for failsafe when suppressor doesn't report keys ──
+    process.stdin.on('data', (data) => {
+      const str = data.toString();
+
+      // Handle Ctrl+C as a safety measure
+      if (str === '\x03') {
+        this._cleanup();
+        process.exit(0);
+      }
+
+      // If suppressor isn't active, count stdin keystrokes
+      if (!this.state.suppressorActive) {
+        this.state.keyCount += 1;
+      }
+    });
+
+    // ── Start the render loop ──
+    this.renderer.startLoop();
+  }
+
+  _render(cols, rows) {
+    this.tick++;
+
+    if (this.state.unlocking) {
+      return renderUnlockSequence(cols, rows, this.tick, this.state.unlockTick);
+    }
+
+    let result;
+    switch (this.skin) {
+      case 'cat':
+        result = renderCat(cols, rows, this.state, this.tick);
+        break;
+      case 'toddler':
+        result = renderToddler(cols, rows, this.state, this.tick);
+        break;
+      case 'prank':
+        result = renderPrank(cols, rows, this.state, this.tick);
+        break;
+      case 'hacker':
+        result = renderHacker(cols, rows, this.state, this.tick);
+        break;
+      case 'arcade':
+        result = renderArcade(cols, rows, this.state, this.tick);
+        break;
+      case 'zen':
+        result = renderZen(cols, rows, this.state, this.tick);
+        break;
+      case 'clean':
+      default:
+        result = renderClean(cols, rows, this.state, this.tick);
+        break;
+    }
+
+    // Update mouse regions based on render output
+    if (result.buttonRegion) {
+      this.mouse.addRegion(
+        'unvoid',
+        result.buttonRegion.x,
+        result.buttonRegion.y,
+        result.buttonRegion.width,
+        result.buttonRegion.height,
+        () => this._onUnvoid()
+      );
+    }
+
+    // Prank mode: secret exit zone
+    if (result.secretRegion) {
+      this.mouse.addRegion(
+        'prank-exit',
+        result.secretRegion.x,
+        result.secretRegion.y,
+        result.secretRegion.width,
+        result.secretRegion.height,
+        (event) => {
+          if (checkPrankExit(event.x, event.y, cols)) {
+            this._onUnvoid();
+          }
+        }
+      );
+    }
+
+    return result.lines;
+  }
+
+  _setupMouseRegions() {
+    // Listen for any click event (for prank mode detection)
+    this.mouse.on('click', (event) => {
+      // Prank mode handles its own exit logic through the region callback
+    });
+  }
+
+  _onUnvoid() {
+    if (this.state.unlocking) return; // Prevent double trigger
+    
+    // Stop suppressor and listener immediately but keep rendering UI loop
+    this.suppressor.stop();
+    this.mouse.stop();
+    this.state.unlocking = true;
+    this.state.unlockTick = this.tick;
+
+    // Wait exactly 60 frames (~1.0s) for vault door animation then display summary
+    setTimeout(() => {
+        this._cleanup();
+        
+        const durationMs = Date.now() - this.state.startTime;
+        const mins = Math.floor(durationMs / 60000);
+        const secs = Math.floor((durationMs % 60000) / 1000);
+        const timeStr = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+        
+        console.log('');
+        console.log(chalk.greenBright.bold('  ✅ Keyboard UNVOIDED! You\'re free.'));
+        console.log(chalk.dim('  ┌─────────────────────────────────────┐'));
+        console.log(chalk.dim('  │  ') + chalk.white('SESSION SUMMARY') + chalk.dim('                    │'));
+        console.log(chalk.dim('  ├─────────────────────────────────────┤'));
+        console.log(chalk.dim('  │  ') + chalk.cyan('Time Locked     :') + chalk.whiteBright(` ${timeStr}`.padEnd(16)) + chalk.dim(' │'));
+        console.log(chalk.dim('  │  ') + chalk.magenta('Mode Selected   :') + chalk.whiteBright(` ${this.skin}`.padEnd(16)) + chalk.dim(' │'));
+        console.log(chalk.dim('  │  ') + chalk.yellow('Total Keys Block:') + chalk.whiteBright(` ${this.state.keyCount.toLocaleString()}`.padEnd(16)) + chalk.dim(' │'));
+        console.log(chalk.dim('  └─────────────────────────────────────┘\n'));
+        
+        process.exit(0);
+    }, 1000);
+  }
+
+  _cleanup() {
+    if (!this.running) return;
+    this.running = false;
+
+    // Stop everything in order
+    this.mouse.stop();
+    this.suppressor.stop();
+    this.renderer.teardown();
+
+    if (this.skin === 'prank') {
+      resetPrankState();
+    }
+
+    // Remove handlers
+    process.removeListener('SIGINT', this._boundCleanup);
+    process.removeListener('SIGTERM', this._boundCleanup);
+  }
+
+  _showSplash() {
+    // Brief splash before entering full-screen
+    console.log('');
+    console.log(chalk.cyan.bold('  ◆ KeyVoid'));
+    console.log(chalk.dim(`  Starting in ${this.skin} mode...`));
+
+    if (this.skin === 'prank') {
+      console.log(chalk.dim('  Secret exit: triple-click top-right corner'));
+    }
+
+    console.log(chalk.dim('  Failsafe: hold ESC + SPACE for 5 seconds'));
+    console.log('');
+  }
+}

package/src/engine/permissions.js

@@ -0,0 +1,107 @@
+// ─── OS Permissions Checker ──────────────────────────────────────────
+// Detects the current OS and checks whether the necessary permissions
+// are granted for global keyboard interception.
+
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+
+export function checkPermissions() {
+  const platform = process.platform;
+  const result = { ok: false, platform, message: '', guide: '' };
+
+  switch (platform) {
+    case 'darwin':
+      result.ok = checkMacOS();
+      if (!result.ok) {
+        result.message = 'Accessibility permission required';
+        result.guide = [
+          '',
+          chalk.yellow.bold('  ⚠  macOS Accessibility Permission Required'),
+          '',
+          chalk.white('  KeyVoid needs permission to intercept keyboard events.'),
+          chalk.white('  Please follow these steps:'),
+          '',
+          chalk.cyan('  1. ') + chalk.white('Open ') + chalk.bold('System Settings'),
+          chalk.cyan('  2. ') + chalk.white('Go to ') + chalk.bold('Privacy & Security → Accessibility'),
+          chalk.cyan('  3. ') + chalk.white('Click ') + chalk.bold('+') + chalk.white(' and add your ') + chalk.bold('Terminal app'),
+          chalk.cyan('  4. ') + chalk.white('Toggle the switch ') + chalk.bold('ON'),
+          chalk.cyan('  5. ') + chalk.white('Re-run ') + chalk.bold('keyvoid'),
+          '',
+          chalk.dim('  Tip: Add the terminal you\'re using (Terminal.app, iTerm2, etc.)'),
+          '',
+        ].join('\n');
+      }
+      break;
+
+    case 'win32':
+      // Windows generally allows user-level hooks without special permissions
+      result.ok = true;
+      result.message = 'Windows hooks available';
+      break;
+
+    case 'linux':
+      result.ok = checkLinux();
+      if (!result.ok) {
+        result.message = 'Missing dependencies or permissions';
+        result.guide = [
+          '',
+          chalk.yellow.bold('  ⚠  Linux Dependencies Required'),
+          '',
+          chalk.white('  KeyVoid needs xinput to disable keyboard devices.'),
+          '',
+          chalk.cyan('  Ubuntu/Debian: ') + chalk.white('sudo apt install xinput'),
+          chalk.cyan('  Fedora:        ') + chalk.white('sudo dnf install xinput'),
+          chalk.cyan('  Arch:          ') + chalk.white('sudo pacman -S xorg-xinput'),
+          '',
+          chalk.dim('  Note: Wayland is not fully supported. X11 is required.'),
+          '',
+        ].join('\n');
+      }
+      break;
+
+    default:
+      result.message = `Unsupported platform: ${platform}`;
+      result.guide = chalk.red(`  KeyVoid does not support ${platform} yet.`);
+      break;
+  }
+
+  return result;
+}
+
+function checkMacOS() {
+  // Attempt a quick CGEventTap test — if it fails, Accessibility is not granted.
+  // We'll rely on the actual helper to report failure at runtime.
+  // For now, optimistically return true and handle failure in the suppressor.
+  try {
+    // Check if the terminal process has accessibility via tccutil (unreliable)
+    // Instead, we'll just check if we can find swiftc/swift
+    execSync('which swift', { stdio: 'pipe' });
+    return true;
+  } catch {
+    // Even without swift, cc (clang) should be available
+    try {
+      execSync('which cc', { stdio: 'pipe' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+function checkLinux() {
+  try {
+    execSync('which xinput', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getPlatformName() {
+  switch (process.platform) {
+    case 'darwin': return 'macOS';
+    case 'win32':  return 'Windows';
+    case 'linux':  return 'Linux';
+    default:       return process.platform;
+  }
+}

package/src/engine/suppressor/helpers/linux-helper.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+Linux Keyboard Suppressor for KeyVoid
+Uses xinput to disable keyboard input devices.
+Requires: xinput (xorg-xinput package)
+
+Output protocol (stdout):
+  STARTED           — helper is active and blocking keys
+  K:<keycode>:<1|0> — key event (via /dev/input if available)
+  FAILSAFE          — not implemented in this helper (handled by Node.js)
+"""
+
+import subprocess
+import sys
+import signal
+import os
+import time
+import select
+
+disabled_ids = []
+input_fds = []
+
+
+def get_keyboard_ids():
+    """Find all physical keyboard device IDs via xinput."""
+    try:
+        result = subprocess.run(
+            ['xinput', 'list'],
+            capture_output=True, text=True, timeout=5
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return []
+
+    ids = []
+    for line in result.stdout.split('\n'):
+        line_lower = line.lower()
+        # Match keyboard devices, skip virtual/core devices
+        if 'keyboard' in line_lower and \
+           'virtual' not in line_lower and \
+           'xtest' not in line_lower and \
+           'power' not in line_lower and \
+           'video' not in line_lower and \
+           'consumer' not in line_lower:
+            # Extract id=NUMBER
+            if 'id=' in line:
+                try:
+                    id_str = line.split('id=')[1].split()[0].strip()
+                    ids.append(id_str)
+                except (IndexError, ValueError):
+                    pass
+    return ids
+
+
+def disable_keyboards(ids):
+    """Disable keyboard devices via xinput."""
+    global disabled_ids
+    for dev_id in ids:
+        try:
+            subprocess.run(
+                ['xinput', 'disable', dev_id],
+                capture_output=True, timeout=5
+            )
+            disabled_ids.append(dev_id)
+        except Exception:
+            pass
+
+
+def enable_keyboards():
+    """Re-enable all previously disabled keyboard devices."""
+    global disabled_ids
+    for dev_id in disabled_ids:
+        try:
+            subprocess.run(
+                ['xinput', 'enable', dev_id],
+                capture_output=True, timeout=5
+            )
+        except Exception:
+            pass
+    disabled_ids = []
+
+
+def try_grab_evdev():
+    """
+    Attempt to exclusively grab keyboard /dev/input devices.
+    This is more reliable than xinput disable but requires root.
+    Returns list of file descriptors.
+    """
+    import struct
+    import fcntl
+
+    EVIOCGRAB = 0x40044590
+    fds = []
+
+    try:
+        for entry in os.listdir('/dev/input/'):
+            if not entry.startswith('event'):
+                continue
+            path = f'/dev/input/{entry}'
+            try:
+                fd = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+                # Check if it's a keyboard (EV_KEY capability)
+                # Simplified: try to grab it
+                fcntl.ioctl(fd, EVIOCGRAB, 1)
+                fds.append(fd)
+            except (OSError, IOError):
+                try:
+                    os.close(fd)
+                except Exception:
+                    pass
+    except Exception:
+        pass
+
+    return fds
+
+
+def release_evdev(fds):
+    """Release grabbed evdev devices."""
+    import fcntl
+    EVIOCGRAB = 0x40044590
+    for fd in fds:
+        try:
+            fcntl.ioctl(fd, EVIOCGRAB, 0)
+            os.close(fd)
+        except Exception:
+            pass
+
+
+def cleanup(sig=None, frame=None):
+    """Clean up: re-enable keyboards and release evdev grabs."""
+    enable_keyboards()
+    release_evdev(input_fds)
+    sys.exit(0)
+
+
+# Register signal handlers for clean shutdown
+signal.signal(signal.SIGTERM, cleanup)
+signal.signal(signal.SIGINT, cleanup)
+
+# Register atexit handler as extra safety
+import atexit
+atexit.register(lambda: enable_keyboards())
+
+
+def main():
+    global input_fds
+
+    # Try evdev grab first (requires root, more reliable)
+    if os.geteuid() == 0:
+        input_fds = try_grab_evdev()
+        if input_fds:
+            print("STARTED", flush=True)
+            # Monitor grabbed devices for key events
+            try:
+                while True:
+                    time.sleep(0.1)
+                    # Read events from grabbed devices
+                    for fd in input_fds:
+                        try:
+                            data = os.read(fd, 24)
+                            if len(data) >= 24:
+                                import struct
+                                _, _, ev_type, ev_code, ev_value = struct.unpack(
+                                    'llHHI', data
+                                )
+                                if ev_type == 1:  # EV_KEY
+                                    is_down = 1 if ev_value == 1 else 0
+                                    print(f"K:{ev_code}:{is_down}", flush=True)
+                        except (BlockingIOError, OSError):
+                            pass
+            except KeyboardInterrupt:
+                cleanup()
+            return
+
+    # Fallback: xinput disable
+    keyboard_ids = get_keyboard_ids()
+    if not keyboard_ids:
+        print("ERROR: No keyboard devices found", file=sys.stderr, flush=True)
+        sys.exit(1)
+
+    disable_keyboards(keyboard_ids)
+    print("STARTED", flush=True)
+
+    # Keep running until signal
+    try:
+        while True:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        cleanup()
+
+
+if __name__ == '__main__':
+    main()

package/src/engine/suppressor/helpers/macos-helper.swift

@@ -0,0 +1,108 @@
+// ─── macOS Keyboard Suppressor ───────────────────────────────────────
+// Uses CGEventTap to intercept and suppress all keyboard events.
+// Requires Accessibility permission in System Settings.
+//
+// Compile: swiftc -O macos-helper.swift -o keyvoid-macos-helper
+// Run:     ./keyvoid-macos-helper
+//
+// 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
+//   ERROR:<message>   — something went wrong
+
+import Cocoa
+import Foundation
+
+// ── State ──
+var escPressed = false
+var spacePressed = false
+var failsafeStart: Date? = nil
+let failsafeSeconds: TimeInterval = 5.0
+
+// ── Signal Handling ──
+signal(SIGTERM) { _ in exit(0) }
+signal(SIGINT)  { _ in exit(0) }
+
+// ── Event Callback ──
+func eventCallback(
+  proxy: CGEventTapProxy,
+  type: CGEventType,
+  event: CGEvent,
+  refcon: UnsafeMutableRawPointer?
+) -> Unmanaged<CGEvent>? {
+
+  // If the tap is disabled by the system, re-enable it
+  if type == .tapDisabledByTimeout || type == .tapDisabledByUserInput {
+    if let tap = refcon {
+      let machPort = Unmanaged<CFMachPort>.fromOpaque(tap).takeUnretainedValue()
+      CGEvent.tapEnable(tap: machPort, enable: true)
+    }
+    return Unmanaged.passRetained(event)
+  }
+
+  let keycode = event.getIntegerValueField(.keyboardEventKeycode)
+  let isDown = (type == .keyDown || type == .flagsChanged)
+
+  // Output key event to Node.js
+  print("K:\(keycode):\(isDown ? 1 : 0)")
+  fflush(stdout)
+
+  // ── Failsafe: Esc (53) + Space (49) held for 5 seconds ──
+  if type == .keyDown {
+    if keycode == 53 { escPressed = true }
+    if keycode == 49 { spacePressed = true }
+  } else if type == .keyUp {
+    if keycode == 53 { escPressed = false }
+    if keycode == 49 { spacePressed = false }
+  }
+
+  if escPressed && spacePressed {
+    if failsafeStart == nil {
+      failsafeStart = Date()
+    } else if Date().timeIntervalSince(failsafeStart!) >= failsafeSeconds {
+      print("FAILSAFE")
+      fflush(stdout)
+      exit(0)
+    }
+  } else {
+    failsafeStart = nil
+  }
+
+  // Return nil to suppress (block) the keyboard event
+  return nil
+}
+
+// ── Main ──
+// NX_SYSDEFINED (type 14) captures media/function keys (volume, brightness, etc.)
+let eventMask: CGEventMask = (
+  (1 << CGEventType.keyDown.rawValue) |
+  (1 << CGEventType.keyUp.rawValue) |
+  (1 << CGEventType.flagsChanged.rawValue) |
+  (1 << 14) // NX_SYSDEFINED — media keys, function keys
+)
+
+guard let eventTap = CGEvent.tapCreate(
+  tap: .cgSessionEventTap,
+  place: .headInsertEventTap,
+  options: .defaultTap,
+  eventsOfInterest: eventMask,
+  callback: eventCallback,
+  userInfo: nil
+) else {
+  fputs("ERROR: Failed to create event tap. Grant Accessibility permission in System Settings → Privacy & Security → Accessibility\n", stderr)
+  exit(1)
+}
+
+// Store the tap reference for re-enabling on timeout
+let tapRef = Unmanaged.passUnretained(eventTap).toOpaque()
+
+let runLoopSource = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, eventTap, 0)
+CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, .commonModes)
+CGEvent.tapEnable(tap: eventTap, enable: true)
+
+print("STARTED")
+fflush(stdout)
+
+// Run the event loop forever (until killed or failsafe triggers)
+CFRunLoopRun()