js_lis 3.1.2 → 3.1.3

package/README.md

@@ -1,164 +1,135 @@
-# js_lis
-
-**js_lis** is a JavaScript on-screen keyboard utility designed to reduce the risk of keystroke interception by avoiding direct hardware keyboard input in sensitive workflows.
-
-NPM package: [https://www.npmjs.com/package/js_lis](https://www.npmjs.com/package/js_lis)
-
-Web test Login + SOSK: [https://sosk-login-js-six.vercel.app](https://sosk-login-js-six.vercel.app).
-
----
-
-## English
-
-### Overview
-
-`js_lis` provides a virtual keyboard interface that can be integrated into web pages or web-based interfaces.  
-It is intended for high-risk input scenarios where users want an additional defense layer against keylogging.
-
-### Security Note (Keylogger and Bettercap)
-
-- `js_lis` can help reduce exposure to **traditional keyloggers** that rely on physical keystroke capture.
-- It is also intended to reduce risk from interception workflows commonly demonstrated with network attack tools such as **bettercap** (for example, injected key-capture scripts in compromised environments).
-- No client-side tool can guarantee complete protection. Security still depends on HTTPS, trusted networks, endpoint hygiene, and browser integrity.
-
-### Key Security Features
-
-- **AES-GCM Memory Encryption**: All keystrokes are buffered and encrypted in-memory using the Web Crypto API (AES-256-GCM). The actual DOM elements never store the plaintext values.
-- **Shadow DOM Isolation**: The keyboard UI is rendered inside a `closed` Shadow DOM to prevent malicious external CSS/JS from sniffing or tampering with the keys.
-- **Anti-Clipboard Sniffing**: Blocks unauthorized `copy`, `cut`, and `execCommand("copy"/"cut")` actions to prevent clipboard hijacking.
-- **IME Reconciliation**: Safely handles Input Method Editors (like Thai or Chinese typing) natively without exposing the secure buffer.
-- **Dynamic Scrambling**: Provides an optional dynamic key scramble to thwart clickjacking or screen coordinate tracking.
-
-### Installation
-
-```bash
-npm install js_lis
-```
-
-### Basic Usage
-
-```javascript
-// Example import style (adjust to your project setup)
-import js_lis from "js_lis";
-
-// Initialize according to your app's integration pattern
-// (see your local implementation files for exact wiring)
-```
-
-### How It Works + ID-based Integration
-
-`js_lis` expects specific DOM IDs:
-
-- `keyboard-container`: container where the virtual keyboard is rendered
-- `toggle`: optional button for show/hide keyboard
-
-When the page loads, create `VirtualKeyboard`.  
-Then the library listens to `INPUT` and `TEXTAREA` focus/click events, tracks the active field, and injects typed characters via the virtual keys.
-
-```html
-<input id="secure-input" type="password" placeholder="Enter password" />
-<button id="toggle" type="button">Toggle Keyboard</button>
-<div id="keyboard-container"></div>
-```
-
-```javascript
-import { VirtualKeyboard } from "./VirtualKeyboard.js";
-
-window.addEventListener("DOMContentLoaded", () => {
-  const keyboard = new VirtualKeyboard();
-
-  // Example of ID-based element access in JS
-  const secureInput = document.getElementById("secure-input");
-  if (secureInput) secureInput.focus();
-});
-```
-
-### Recommended Deployment Practices
-
-- Serve over HTTPS only.
-- Use a strict Content Security Policy (CSP).
-- Avoid running on untrusted or MITM-prone networks.
-- Keep browser and OS security patches up to date.
-- Pair with endpoint protection and monitoring.
-
----
-
-## ภาษาไทย (ทางการ)
-
-### ภาพรวม
-
-`js_lis` เป็นเครื่องมือคีย์บอร์ดเสมือน (Virtual Keyboard) สำหรับ JavaScript ที่ออกแบบมาเพื่อลดความเสี่ยงจากการดักจับการพิมพ์ โดยหลีกเลี่ยงการป้อนข้อมูลผ่านคีย์บอร์ดฮาร์ดแวร์โดยตรงในขั้นตอนที่มีความอ่อนไหวด้านความปลอดภัย
-
-อ้างอิงแพ็กเกจบน npm: [https://www.npmjs.com/package/js_lis](https://www.npmjs.com/package/js_lis)
-
-ตัวอย่างหน้า Login + SOSK: [https://sosk-login-js-six.vercel.app](https://sosk-login-js-six.vercel.app).
-
-### หมายเหตุด้านความปลอดภัย (Keylogger และ Bettercap)
-
-- `js_lis` สามารถช่วยลดความเสี่ยงจาก **keylogger แบบดั้งเดิม** ที่มุ่งดักข้อมูลจากการกดแป้นพิมพ์จริง
-- รวมถึงสามารถช่วยลดความเสี่ยงจากรูปแบบการโจมตีที่มักสาธิตผ่านเครื่องมือเครือข่ายอย่าง **bettercap** (เช่น การแทรกสคริปต์เพื่อดักรับข้อมูลการป้อนในสภาพแวดล้อมที่ถูกบุกรุก)
-- อย่างไรก็ตาม เครื่องมือฝั่งผู้ใช้เพียงอย่างเดียวไม่สามารถรับประกันการป้องกันได้สมบูรณ์ จำเป็นต้องใช้ร่วมกับ HTTPS, เครือข่ายที่เชื่อถือได้, ความปลอดภัยของเครื่องผู้ใช้ และความน่าเชื่อถือของเบราว์เซอร์
-
-### ฟีเจอร์ด้านความปลอดภัยที่สำคัญ
-
-- **การเข้ารหัสหน่วยความจำด้วย AES-GCM**: ทุกการกดแป้นพิมพ์จะถูกบัฟเฟอร์และเข้ารหัสในหน่วยความจำชั่วคราวด้วย Web Crypto API (AES-256-GCM) ข้อความต้นฉบับจะไม่ถูกเก็บเป็น plaintext ใน DOM elements
-- **การแยกส่วนด้วย Shadow DOM**: หน้าคีย์บอร์ดจะถูกเรนเดอร์อยู่ภายใน `closed` Shadow DOM เพื่อป้องกันไม่ให้ CSS/JS จากภายนอกแอบอ่านหรือแก้ไขปุ่มคีย์บอร์ด
-- **ป้องกันการแอบอ่านคลิปบอร์ด (Anti-Clipboard Sniffing)**: บล็อกการดักจับคำสั่ง `copy`, `cut`, และ `execCommand` ที่ไม่ได้รับอนุญาตเพื่อป้องกันการขโมยข้อมูลจากคลิปบอร์ด
-- **รองรับ IME อย่างปลอดภัย**: จัดการกับการพิมพ์ผ่าน Input Method Editors (เช่น ภาษาไทย) ได้อย่างถูกต้องโดยที่ยังคงแยกบักเฟอร์ข้อมูลอย่างปลอดภัย
-- **การสลับตำแหน่งปุ่ม (Dynamic Scrambling)**: มีฟังก์ชันสลับตำแหน่งปุ่มแบบสุ่มเพื่อป้องกันการติดตามพิกัดการคลิกบนหน้าจอหรือ clickjacking
-
-### การติดตั้ง
-
-```bash
-npm install js_lis
-```
-
-### การใช้งานเบื้องต้น
-
-```javascript
-// ตัวอย่างการนำเข้า (ปรับตามโครงสร้างโปรเจกต์ของท่าน)
-import js_lis from "js_lis";
-
-// เรียกใช้งานตามรูปแบบการเชื่อมต่อของแอปพลิเคชัน
-```
-
-### หลักการทำงาน + การเรียกใช้ผ่าน ID ใน JavaScript
-
-`js_lis` ต้องอาศัย DOM `id` หลักดังนี้
-
-- `keyboard-container`: พื้นที่สำหรับ render คีย์บอร์ดเสมือน
-- `toggle`: ปุ่มสำหรับสลับแสดง/ซ่อนคีย์บอร์ด (ถ้ามี)
-
-เมื่อหน้าเว็บโหลดเสร็จ ให้สร้าง `VirtualKeyboard` จากนั้นระบบจะดักเหตุการณ์ focus/click ของ `INPUT` และ `TEXTAREA` เพื่อระบุช่องที่กำลังใช้งาน และป้อนค่าผ่านปุ่มบนคีย์บอร์ดเสมือน
-
-```html
-<input id="secure-input" type="password" placeholder="กรอกรหัสผ่าน" />
-<button id="toggle" type="button">แสดง/ซ่อนคีย์บอร์ด</button>
-<div id="keyboard-container"></div>
-```
-
-```javascript
-import { VirtualKeyboard } from "./VirtualKeyboard.js";
-
-window.addEventListener("DOMContentLoaded", () => {
-  const keyboard = new VirtualKeyboard();
-
-  // ตัวอย่างการเรียกใช้งาน element ผ่าน id
-  const secureInput = document.getElementById("secure-input");
-  if (secureInput) secureInput.focus();
-});
-```
-
-### แนวทางการใช้งานที่แนะนำ
-
-- ให้บริการผ่าน HTTPS เท่านั้น
-- กำหนดนโยบาย Content Security Policy (CSP) อย่างเข้มงวด
-- หลีกเลี่ยงการใช้งานบนเครือข่ายที่ไม่เชื่อถือได้หรือมีความเสี่ยง MITM
-- อัปเดตแพตช์ความปลอดภัยของระบบปฏิบัติการและเบราว์เซอร์อย่างสม่ำเสมอ
-- ใช้งานร่วมกับระบบป้องกันและเฝ้าระวังความปลอดภัยของอุปกรณ์ปลายทาง
-
----
-
-## License
-
-ISC
+# js_lis (SOSK - Secure On-Screen Keyboard)
+
+**js_lis** is a high-security JavaScript on-screen keyboard (SOSK) designed to mitigate the risk of keystroke interception. Unlike traditional virtual keyboards, it employs multi-layered security protocols to protect sensitive data from keyloggers, clipboard sniffers, and man-in-the-browser (MITB) attacks.
+
+NPM package: [https://www.npmjs.com/package/js_lis](https://www.npmjs.com/package/js_lis)  
+Web Test Login + SOSK: [https://sosk-login-js-six.vercel.app](https://sosk-login-js-six.vercel.app)
+
+---
+
+## English
+
+### Overview
+
+`js_lis` provides a secure input interface that isolates user interactions from the host page. It is engineered for scenarios where standard hardware input is too risky, such as financial transactions, credential entry, or private communication.
+
+### Advanced Security Architecture
+
+1.  **AES-GCM Memory Encryption**:
+    *   **SecureBufferStore**: Uses a `WeakMap` to store encrypted buffers associated with input elements. This ensures that even if an attacker leaks the object, the data remains protected.
+    *   **Cryptographic Strength**: Employs **AES-256-GCM** via the Web Crypto API. Each buffer is encrypted with a unique IV (Initialization Vector) generated per write operation.
+    *   **Automatic Fallback**: Gracefully degrades to a non-encrypted buffer in insecure (HTTP) environments where the Web Crypto API is unavailable.
+
+2.  **Shadow DOM Isolation**:
+    *   The keyboard UI is rendered within a **`closed` Shadow DOM**.
+    *   **Isolation**: This prevents the host page's CSS from altering the keyboard appearance (anti-clickjacking) and blocks third-party JavaScript from inspecting the keyboard's internal DOM structure.
+
+3.  **IME Reconciliation Engine**:
+    *   Natively handles Input Method Editors (IME) for languages like Thai, Chinese, or Japanese.
+    *   **Sync Logic**: intercepts `compositionstart`, `compositionupdate`, and `compositionend` events to synchronize complex multi-character inputs with the encrypted secure buffer without exposing intermediate states.
+
+4.  **Anti-Clipboard Sniffing & Secure Paste**:
+    *   **Event Blocking**: Intercepts and blocks unauthorized `copy` and `cut` events when the virtual keyboard is active.
+    *   **Command Sanitization**: Monkey-patches `document.execCommand` to disable clipboard operations programmatically.
+    *   **Secure Paste**: Implements an explicit `securePaste()` method using the `navigator.clipboard` API to ensure data only enters the secure buffer when intended.
+
+5.  **Physical Keyboard Synchronization**:
+    *   Captures hardware `keydown` and `input` events to keep the secure buffer updated in real-time, even when a user switches between virtual and physical input.
+
+### Installation
+
+```bash
+npm install js_lis
+```
+
+### Technical Integration
+
+The recommended implementation uses a singleton pattern to manage the keyboard instance across your application.
+
+#### DOM Requirements
+- `keyboard-container`: The target div where the keyboard will be injected.
+- `toggle` (Optional): A button to show/hide the keyboard.
+
+```html
+<input id="login-input" type="password" placeholder="Enter Password" />
+<div id="keyboard-container"></div>
+<button id="toggle">Toggle Keyboard</button>
+```
+
+#### Initialization
+```javascript
+import { getKeyboard } from "js_lis/main.js";
+
+// Get the existing singleton instance
+const keyboard = getKeyboard();
+
+// The keyboard automatically monitors all INPUT and TEXTAREA elements.
+// To manually focus an element and start secure buffer tracking:
+const input = document.getElementById("login-input");
+keyboard.setCurrentInput(input);
+```
+
+### Supported Layouts
+- **Full**: QWERTY + Numpad + Symbols.
+- **English/Thai**: Standard localized layouts.
+- **Numpad**: Numeric entry only.
+- **Symbols**: Special characters.
+- **Dynamic Scramble**: Optional randomization of key positions to thwart coordinate tracking.
+
+---
+
+## ภาษาไทย (Technical Overview)
+
+### ภาพรวม
+`js_lis` คือระบบคีย์บอร์ดเสมือนที่มีความปลอดภัยสูง (Secure On-Screen Keyboard - SOSK) ออกแบบมาเพื่อป้องกันการดักจับข้อมูลการพิมพ์ (Keystroke Interception) โดยใช้เทคโนโลยีการป้องกันหลายชั้นเพื่อความปลอดภัยสูงสุดในระดับ Memory และ DOM Level
+
+### สถาปัตยกรรมด้านความปลอดภัยขั้นสูง
+
+1.  **การเข้ารหัสหน่วยความจำระดับ AES-GCM**:
+    *   **SecureBufferStore**: ใช้ `WeakMap` ในการเก็บข้อมูลจำลอง (Buffer) ที่ถูกเข้ารหัสแยกตาม Input Element เพื่อป้องกันการรั่วไหลของข้อมูลหาก Object ถูกเข้าถึงโดยไม่ได้รับอนุญาต
+    *   **มาตรฐานการเข้ารหัส**: ใช้ **AES-256-GCM** ผ่าน Web Crypto API โดยทุกการอัปเดตข้อมูลจะมีการสร้าง IV (Initialization Vector) ใหม่เสมอ
+    *   **ระบบสำรอง (Fallback)**: หากใช้งานผ่านโปรโตคอล HTTP (ซึ่งไม่มี SubtleCrypto) ระบบจะเปลี่ยนมาใช้การเก็บข้อมูลแบบ Plaintext โดยอัตโนมัติ
+
+2.  **การแยกส่วนด้วย Shadow DOM (Closed Mode)**:
+    *   หน้าจอคีย์บอร์ดจะถูกสร้างขึ้นภายใน **Closed Shadow DOM**
+    *   **การแยกส่วน (Isolation)**: ป้องกันไม่ให้ CSS จากภายนอกเข้ามาแก้ไขหน้าตาคีย์บอร์ด (ป้องกัน Clickjacking) และป้องกันไม่ให้ JavaScript จากภายนอกสามารถอ่านโครงสร้างปุ่มภายในได้
+
+3.  **ระบบประสานงาน IME (IME Reconciliation Engine)**:
+    *   รองรับการพิมพ์ภาษาไทยและภาษาอื่นๆ ที่ต้องใช้การประสมคำ (Composition) ได้อย่างสมบูรณ์
+    *   **การซิงโครไนซ์**: ดักจับ Event `compositionstart/update/end` เพื่อนำข้อมูลมาประมวลผลร่วมกับ Secure Buffer โดยที่ข้อมูลล่าสุดจะถูกเข้ารหัสทันทีที่จบการประสมคำ
+
+4.  **การป้องกันคลิปบอร์ดและการวางข้อมูลอย่างปลอดภัย (Anti-Clipboard)**:
+    *   **การบล็อกเหตุการณ์**: บล็อกคำสั่ง `copy` และ `cut` เมื่อมีการใช้งานคีย์บอร์ดเสมือน
+    *   **การป้องกันโปรแกรมมิ่ง**: ทำการ Override `document.execCommand` เพื่อปิดการทำงานที่เกี่ยวกับคลิปบอร์ดผ่านสคริปต์
+    *   **Secure Paste**: รองรับการวางข้อมูลผ่าน `navigator.clipboard` API โดยเฉพาะเพื่อให้มั่นใจว่าข้อมูลจะถูกส่งเข้าสู่ Secure Buffer โดยตรง
+
+5.  **การซิงโครไนซ์กับคีย์บอร์ดจริง**:
+    *   ติดตามเหตุการณ์ `keydown` และ `input` จากคีย์บอร์ดฮาร์ดแวร์เพื่ออัปเดตข้อมูลใน Secure Buffer ให้ตรงกันเสมอ ไม่ว่าจะพิมพ์ผ่านช่องทางใด
+
+### การเรียกใช้งานทางเทคนิค
+
+แนะนำให้ใช้งานในรูปแบบ Singleton เพื่อประสิทธิภาพสูงสุด
+
+```javascript
+import { getKeyboard } from "js_lis/main.js";
+
+// เข้าถึง Instance ที่ถูกสร้างไว้แล้ว
+const osk = getKeyboard();
+
+// ระบบจะคอยตรวจสอบ INPUT และ TEXTAREA บนหน้าเว็บโดยอัตโนมัติ
+// หากต้องการกำหนดช่องรับข้อมูลที่ต้องการเริ่มต้นใช้งาน:
+const myInput = document.getElementById("password-field");
+osk.setCurrentInput(myInput);
+```
+
+### เลย์เอาต์ที่รองรับ
+- **Full**: คีย์บอร์ดเต็มรูปแบบ (QWERTY + ตัวเลข + สัญลักษ์)
+- **English / Thai**: คีย์บอร์ดภาษาอังกฤษและภาษาไทยมาตราฐาน
+- **Numpad / Symbols**: เฉพาะตัวเลขหรือสัญลักษณ์พิเศษ
+- **Dynamic Scramble**: ฟังก์ชันสลับตำแหน่งปุ่มแบบสุ่มเพื่อป้องกันการติดตามพิกัดการคลิก
+
+---
+
+## License
+
+ISC

package/main.js

@@ -1,4 +1,32 @@
-import { VirtualKeyboard } from "./VirtualKeyboard.js";
-
-// สร้างออบเจกต์คีย์บอร์ดแล้ว export ทันที (ไม่เอาไปแปะไว้ใน window.keyboard แล้ว)
-export const keyboard = new VirtualKeyboard();
+import { VirtualKeyboard } from "./VirtualKeyboard.js";
+
+let keyboardInstance = null;
+
+// init + singleton
+function initKeyboard() {
+  if (keyboardInstance) return keyboardInstance;
+
+  const container = document.getElementById("keyboard-container");
+  if (!container) {
+    console.warn("Keyboard container not found");
+    return null;
+  }
+
+  keyboardInstance = new VirtualKeyboard();
+  return keyboardInstance;
+}
+
+// getter (ไว้ใช้จากที่อื่น ถ้าจำเป็น)
+export function getKeyboard() {
+  return keyboardInstance;
+}
+
+// init ตอน DOM พร้อม
+window.addEventListener("DOMContentLoaded", () => {
+  try {
+    initKeyboard();
+    console.log("Keyboard initialized safely");
+  } catch (err) {
+    console.error("Keyboard init error:", err);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js_lis",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"