FastKeylogger 0.1.2 [ALPHA] — Native Raw Keystroke Logger, Typing Biometrics & Stream Compression

---

⚡ High-performance raw keystroke logger, biometric typing cadence telemetry, and .keybin dual-format streaming engine for Java.

FastKeylogger intercepts raw Windows keyboard events directly via FastKeyboard, extracts high-resolution behavioral dwell/flight-time dynamics and keystroke corrections, and compresses streams in real-time into binary .keybin logs via FastFileFormat & FastBinary.

---

Quick Start

import fastkeylogger.*;
import java.nio.file.Path;
import java.util.List;

public class Demo {
    public static void main(String[] args) throws Exception {
        Path logDir = Path.of("logs/keyboard");
        TextReconstructor reconstructor = new TextReconstructor();

        // 1. Live background capture
        try (FastKeylogger logger = new FastKeylogger(logDir, 5000)) {
            logger.addListener(reconstructor);
            logger.addListener(event -> {
                System.out.printf("Key '%c' dwell=%dms corr=%b\n",
                        event.character(), event.durationMs(), event.isCorrection());
            });

            logger.start();
            Thread.sleep(4000);
            logger.stop(); // Flushes to timestamped .keybin
        }

        // 2. High-speed FastFileFormat codec & reconstructed text
        Path sessionFile = logDir.resolve("session.keybin");
        List<TypingEvent> events = KeybinCodec.readFromFile(sessionFile);
        System.out.println("Reconstructed text: " + reconstructor.getText());
    }
}

---

Table of Contents

• Quick Start
• Why FastKeylogger?
• Key Features
• Real-World Scenarios
• Performance Benchmarks
• API Quick Reference
• Technical Examples & Hero Demos
• Installation
• Documentation
• Platform Support
• Related Projects
• License

---

Why FastKeylogger?

Standard Java input listeners (java.awt.event.KeyListener, Swing, JavaFX) are strictly application-focused and synthetic:

• Window Focus Requirement: Standard Java only receives keystrokes when its own GUI window has active OS focus. Keystrokes in other applications are completely invisible.
• Lost Hardware Dynamics: AWT collapses physical key transitions into high-level character typing events, discarding exact hardware dwell times (how long a key was physically held down) and flight times (inter-key pause duration).
• Text Stream Churn & Memory: Naive text loggers generate massive GC allocations and bulky JSON/plaintext files that choke disk I/O during long sessions.

FastKeylogger solves this by bridging hardware RawInput with binary serialization:

Feature	Java AWT / Swing	FastKeylogger
Global Background Capture	❌ Focused Window Only	✅ Global OS-Wide (Background)
Microsecond Dwell Time	❌ Lost	✅ Precise Key Press Duration
Inter-Key Flight Time	❌ Unreliable / EDT Lag	✅ Hardware-Exact Cadence
Correction & Backspace Analysis	❌ Manual Parsing	✅ Built-in TextReconstructor
Storage Format	Bloated Plaintext / JSON	Compact .keybin (FastFileFormat)
Decoding Throughput	~100k events/sec	> 58.8 Million events/sec

---

Key Features

• ⌨️ Win32 Raw Input Interception — Sub-millisecond keystroke telemetry capturing raw scan codes and virtual keys via FastKeyboard.
• ⏱️ Biometric Cadence Dynamics — Precise dwell-time (key press duration) and flight-time (inter-key intervals) measurement.
• ⚡ FastFileFormat .keybin Compression — Delta-timestamped VarInt event serialization (Payload ID 0x0004).
• 🔤 Real-Time Text Reconstruction — Backspace-aware text accumulator and state tracker (TextReconstructor).
• 📦 Zero Heavy Dependencies — Native-speed pure Java 17+ core backed by FastCore, FastBinary, and FastFileFormat.

---

Real-World Scenarios

• 🛡️ Continuous Biometric Authentication — Verifying user identity via unique keystroke rhythm patterns and behavioral cadence.
• 🤖 AI Agent Telemetry & Imitation — Capturing fine-grained typing cadences, hesitation pauses, and self-corrections for autonomous agents.
• 📊 Ergonomics & Speed Analytics — Profiling real-world WPM, error rates, and burst typing velocities.
• 📑 Audit & Recovery Logging — Crash-resilient background typing preservation with microsecond precision.

---

Performance Benchmarks

FastKeylogger is profiled using JMH to guarantee maximum stream throughput and zero dropped input packets.

Benchmark Operation	Score (ops/ms)	Event Throughput	Memory Overhead
Binary Stream Decoding (.keybin)	~58,800 ops/ms	> 58.8 Million events/sec	Zero-Copy Streaming
Binary Stream Encoding (.keybin)	~26,800 ops/ms	> 26.8 Million events/sec	Compact VarInt Delta Buffer

Run the benchmarks locally: .\run-benchmark.bat

---

API Quick Reference

Method / Class	Return Type	Description	Docs
new FastKeylogger(path, threshold)	FastKeylogger	Creates a logger flushing every N records into timestamped .keybin files.	Reference
logger.start()	void	Begins background raw keyboard input interception.	Reference
logger.stop()	void	Stops capture and flushes pending memory records to disk.	Reference
logger.addListener(listener)	void	Subscribes to real-time TypingEvent telemetry and rhythm callbacks.	Reference
KeybinCodec.encode(events)	byte[]	Serializes typing events into compressed FastFileFormat binary byte array.	Reference
KeybinCodec.decode(bytes)	List<TypingEvent>	High-speed zero-copy deserialization from .keybin binary stream.	Reference
reconstructor.getText()	String	Returns live reconstructed text with backspace state handling.	Reference

---

Technical Examples & Hero Demos

Case	Java Example	Launcher	Description
Live Typing Streamer & Reconstructor	Demo.java	run-demo.bat	4-second live raw recording, dwell time logging, .keybin compression, and text reconstruction.
JMH Microbenchmark Suite	Benchmark.java	run-benchmark.bat	High-throughput encoding/decoding benchmarks for 1,000-event telemetry streams.

---

Installation

Option 1: Maven (JitPack)

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastKeylogger</artifactId>
        <version>0.1.2</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastKeyboard</artifactId>
        <version>0.1.0</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastFileFormat</artifactId>
        <version>0.1.0</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastBinary</artifactId>
        <version>0.1.0</version>
    </dependency>
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>fastcore</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastKeylogger:0.1.2'
    implementation 'com.github.andrestubbe:FastKeyboard:0.1.0'
    implementation 'com.github.andrestubbe:FastFileFormat:0.1.0'
    implementation 'com.github.andrestubbe:FastBinary:0.1.0'
    implementation 'com.github.andrestubbe:fastcore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest JARs directly to add them to your classpath:

1. ⌨️ FastKeylogger-0.1.2.jar (Typing Logger & Rhythm Engine)
2. ⚡ FastKeyboard-0.1.0.jar (Native Win32 Raw Keyboard Input)
3. 📄 FastFileFormat-0.1.0.jar (Dual Binary & Text File Format)
4. ⚡ FastBinary-0.1.0.jar (VarInt & Binary Packing)
5. ⚙️ fastcore-0.1.0.jar (Foundation Library)

---

Documentation

• REFERENCE.md: Full API reference and method signatures.
• PHILOSOPHY.md: Architectural design principles and biometric rhythm telemetry.
• CHANGELOG.md: Release history and version notes.
• ROADMAP.md: Future milestones and planned features.
• COMPILE.md: Instructions for compiling from source.

---

Platform Support

Platform	Architecture	Status	Driver / Subsystem
Windows 10 / 11	x64	✅ Fully Supported	Native Win32 WM_INPUT (RawInput via FastKeyboard)
Linux	x64 / AArch64	🚧 Planned	evdev / libinput Direct Hardware Event Stream
macOS	Apple Silicon / x64	🚧 Planned	Quartz Event Taps (CGEventTap)

---

License

MIT License. See LICENSE file for details.

---

Related Projects

• FastKeyboard — Low-level raw keyboard event interceptor
• FastMouseLogger — Raw mouse event logger, .mousebin streaming & heatmaps
• FastHotkey — High-speed global hotkey listener
• FastFileFormat — Universal dual-format binary & text document engine
• FastSharedMemory — Zero-copy inter-process shared memory for Java

---

Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋