js_lis 3.0.0 → 3.1.0

package/README.md

@@ -0,0 +1,164 @@
+# 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