@trap_stevo/devlock/README.md

Protect modern web applications from inspection, tampering, and unauthorized access through real-time detection, checksum enforcement, and customizable response strategies. Monitor developer tools, block key combinations, freeze console output, and enforc

# 🛡️ DevLock

**The Guardian of Frontend Integrity**

A powerful real-time defense system that detects devtools, locks down source visibility, and executes fully customizable countermeasures against inspection and tampering.

---


## 🚀 Features

- Real-time detection of Developer Tools (DevTools)
- Runtime checksum verification (fixed or dynamic)
- Custom violation response methods:
  - Overlay lockout
  - Console freezing
  - Redirects or replacement
  - DOM blanking
  - Session and localStorage lockdown
- Full customization with callbacks and overlays
- Dev mode toggle for safe development
- Lightweight and framework-agnostic

---


## 📦 Installation

```bash
npm install @trap_stevo/devlock
```

---


## 🔧 Usage

```js
import { DevLock } from "@trap_stevo/devlock";

const devLock = new DevLock({
     freezeConsole : true,
     verifyChecksum : true,
     checksumMode : "dynamic",
     redirectURL : "/unauthorized",
     violationMethod : "overlay,external",
     overlayMessage : "⚠️ Unauthorized action detected.",
     onDevToolsOpen : () => console.warn("DevTools access blocked."),
     onViolation : (status) => console.log("Violation triggered:", status)
});

devLock.start();
```

---


## 🧠 Violation Methods

| Method         | Description                                |
|----------------|--------------------------------------------|
| `redirect`     | Navigate to a specified URL                |
| `replace`      | Replace the page with `about:blank`        |
| `blank`        | Wipe the DOM contents                      |
| `close`        | Attempt to close the window                |
| `overlay`      | Show a full-screen warning overlay         |
| `external`     | Redirect to browser homepage or URL        |
| `lockStorage`  | Block access to `localStorage/sessionStorage` |

Multiple methods may be combined: `"overlay,external"`

---


## 🧪 Checksum Modes

- `fixed` — compare script hashes against provided list
- `dynamic` — remember initial hashes per session and alert on changes

```js
expectedChecksums : {
     "https://yourdomain.com/js/app.js" : "abc123..."
}
```

---


## ✨ Overlay Customization

```js
overlayMessage : "Access denied. Contact administrator.",
overlayConfigurationSettings : {
     background : "#1A1A1A",
     color : "#FF4444",
     fontSize : "28px"
},
overlayNode : "<div style='...'>Custom HTML content</div>"
```

---


## 📘 API Specification

### Public Methods

| Method                         | Description                                                                  |
|--------------------------------|------------------------------------------------------------------------------|
| `start()`                      | Activates detection and begins monitoring for violations.                   |
| `stop()`                       | Deactivates monitoring and restores modified behaviors.                     |
| `status()`                     | Returns an object containing the current lock status.                       |
| `checkNow()`                   | Forces an immediate check for DevTools.                                     |
| `runViolationMethods(string)` | Manually runs one or more violation actions (e.g., `"overlay,blank"`).      |

### Configuration Options

| Option                        | Type                      | Description                                                                 |
|-------------------------------|---------------------------|-----------------------------------------------------------------------------|
| `devMode`                     | `boolean`                 | Enables or disables detection during development.                          |
| `redirectURL`                 | `string`                  | Target URL for redirection.                                                |
| `violationMethod`             | `string`                  | Comma-separated list of response methods.                                  |
| `freezeConsole`              | `boolean`                 | Disables console output methods.                                           |
| `verifyChecksum`             | `boolean`                 | Enables runtime checksum verification.                                     |
| `checksumMode`               | `"fixed" \| "dynamic"`     | Determines if static or dynamic checksums are enforced.                    |
| `expectedChecksums`          | `object`                  | Map of script URLs to expected hashes.                                     |
| `overlayMessage`             | `string`                  | Message shown in the default overlay.                                      |
| `overlayConfigurationSettings`| `object`                  | CSS styles for the overlay.                                                |
| `overlayNode`                | `HTMLElement \| string`    | Custom node or markup to override default overlay.                         |
| `onDevToolsOpen`             | `function`                | Callback triggered when DevTools opens.                                    |
| `onDevToolsClosed`           | `function`                | Callback triggered when DevTools closes.                                   |
| `onViolation`                | `function`                | Callback triggered before violation methods execute.                       |
| `onRightClick`               | `function`                | Callback for right-click blocking.                                         |
| `onBlockedShortcut`          | `function`                | Callback for blocked key combinations.                                     |
| `onBeforePrint`              | `function`                | Callback for `beforeprint` interception.                                   |
| `onDragStart`                | `function`                | Callback for drag start prevention.                                        |

---


## ✨ License

See License in [LICENSE.md](./LICENSE.md)