devtools-guardian 1.0.1

package/README.md

@@ -0,0 +1,192 @@
+# DevTools Guardian 🛡️
+
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![React Support](https://img.shields.io/badge/React-18%20%2F%2019-blue.svg?logo=react)](https://react.dev)
+[![Build Tool: tsup](https://img.shields.io/badge/build-tsup-purple.svg)](https://tsup.egoist.dev/)
+
+**DevTools Guardian** is a lightweight, zero-dependency, and zero-configuration client-side security guard for React applications. It detects when a user opens browser Developer Tools and locks down the interface using an immersive, animated Matrix-inspired security warning overlay to protect your code, intellectual property, and static assets from inspection, cloning, and reverse-engineering.
+
+---
+
+## Key Features
+
+- **Multi-Heuristic DevTools Detection**:
+  - **Docked Mode**: Tracks browser window outer-to-inner aspect ratios (accounts for DPI scaling and device zoom).
+  - **Undocked Mode**: Uses a performance timing probe combined with controlled debugger statements.
+  - **Console Getter Probe**: Employs a blink-free lazy evaluation trick on the console object—triggers instantly when the console pane is rendered, without printing clutter or requiring console-clearing loops.
+- **Vite & Webpack Dev Mode Bypasses**: Intelligent environment detector prevents debugger statement execution on `localhost`, local IPs (`192.168.x.x`, `10.x.x.x`, `172.x.x.x`), and standard node development runtimes. Developers can debug their code locally without getting trapped in warning loops.
+- **Mobile & Touch-Screen Safeguards**: Automatically ignores dynamic address-bar viewport changes on touch screens (such as iOS Safari/Chrome scrolling adjustments) to eliminate false positives.
+- **Zero-Config Stylesheet Injection**: Styles are bundled and injected dynamically. No manual `.css` imports required in consuming projects.
+- **Keyboard Shortcut Interception**: Silently blocks inspection hotkeys:
+  - `F12`
+  - `Ctrl + Shift + I` / `Cmd + Option + I` (DevTools Open)
+  - `Ctrl + Shift + J` / `Cmd + Option + J` (Console Panel)
+  - `Ctrl + Shift + C` / `Cmd + Option + C` (Element Picker)
+  - `Ctrl + U` / `Cmd + Option + U` (View Source)
+  - `Ctrl + S` / `Cmd + S` (Save Page - blocked silently without triggering warning)
+- **Built-in UI Guards**: Optional full-app text selection disabling and right-click context menu blocking.
+- **React 18 & 19 Ready**: Out of the box support, complete with `"use client"` directives for seamless Next.js App Router integrations.
+
+---
+
+## Installation
+
+Install using your preferred package manager:
+
+```bash
+# npm
+npm install devtools-guardian
+
+# pnpm
+pnpm add devtools-guardian
+
+# yarn
+yarn add devtools-guardian
+```
+
+---
+
+## Quick Start
+
+### 1. Protect Your App (Provider Method)
+
+The simplest way is to wrap your root layouts or main page tree inside `<DevToolsProtection />`.
+
+```tsx
+import React from 'react';
+import { DevToolsProtection } from 'devtools-guardian';
+
+export default function App() {
+  return (
+    <DevToolsProtection overlay={true}>
+      <YourAppRoutes />
+    </DevToolsProtection>
+  );
+}
+```
+
+### 2. Custom Detection Trigger (Hook Method)
+
+If you prefer custom actions (e.g., logging attempts, logging out users, hiding specific secret components) instead of displaying the default warning overlay, use the `useDevToolsDetector` hook:
+
+```tsx
+import React, { useEffect } from 'react';
+import { useDevToolsDetector } from 'devtools-guardian';
+
+export default function SensitiveComponent() {
+  const isDevToolsOpen = useDevToolsDetector({
+    disableRightClick: true,
+    disableSelection: false, // allow user to select text
+    blockedKeys: ['F12', 'Ctrl+Shift+I'],
+    onDetect: () => {
+      console.warn('Suspicious activity flagged!');
+      // Trigger API reports or logout here
+    }
+  });
+
+  return (
+    <div>
+      {isDevToolsOpen ? (
+        <div className="secured-message">Sensitive content has been hidden.</div>
+      ) : (
+        <div className="sensitive-data">Confidential Financial Dashboard</div>
+      )}
+    </div>
+  );
+}
+```
+
+### 3. Display warning card manually
+
+You can render the Matrix Warning screen directly when needed.
+
+```tsx
+import React, { useState } from 'react';
+import { DevToolsWarningOverlay } from 'devtools-guardian';
+
+export default function DemoPage() {
+  const [showWarning, setShowWarning] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setShowWarning(true)}>Simulate Defense System</button>
+      
+      {showWarning && (
+        <DevToolsWarningOverlay onClose={() => setShowWarning(false)} />
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `<DevToolsProtection />`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `React.ReactNode` | *Required* | The elements wrapped by the protection layer. |
+| `overlay` | `boolean` | `true` | When `true`, automatically renders the `<DevToolsWarningOverlay />` dialog when DevTools are detected. |
+
+---
+
+### `useDevToolsDetector(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `blockedKeys` | `string[]` | `['Ctrl+Shift+I', 'Ctrl+Shift+J', 'Ctrl+Shift+C', 'Ctrl+U', 'Ctrl+S']` | Keys/shortcuts intercepted and cancelled. |
+| `disableRightClick` | `boolean` | `true` | Disables browser right-click context menus. |
+| `disableSelection` | `boolean` | `true` | Adds CSS user-select styles to prevent layout copying. |
+| `onDetect` | `() => void` | `undefined` | Callback fired when DevTools is first opened. |
+| `onClose` | `() => void` | `undefined` | Callback fired when DevTools is closed. |
+| `pollInterval` | `number` | `1500` | Frequency in ms to check DevTools status. |
+| `thresholdBuffer` | `number` | `0` | Extra pixel offset buffer for docked dimensions. Increase this on custom Electron/web view wrappers. |
+
+---
+
+### `<DevToolsWarningOverlay />`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onClose` | `() => void` | `undefined` | Callback passed to the dialog dismiss button. If not provided, the "Close & return" button will not render. |
+
+---
+
+## How It Works Under the Hood
+
+1. **Docked Window Differences**:
+   Comparing `window.outerWidth` vs `window.innerWidth` and `window.outerHeight` vs `window.innerHeight`. The library applies a high-DPI scaling factor (`window.devicePixelRatio`) to avoid false alarms during page zooming.
+2. **Console Lazy Evaluation (Blink-Free)**:
+   A lightweight probe object is sent to the console via `console.log`. The object overrides `Symbol.toPrimitive` and `toString`. In modern browsers, when DevTools is closed, the console logs are ignored and the methods are never evaluated. When DevTools is opened, the browser's console processes and renders the logged object, which immediately triggers our hook's tracking state.
+3. **Protected Threading & Exception Safety**:
+   Overriding native browser logs temporarily is dangerous. DevTools Guardian executes the probe inside a strict `try...finally` block, ensuring that the original console properties are instantly restored even if third-party console decorators throw unexpected errors.
+
+---
+
+## Local Development & Testing
+
+We have built a developer playground using Vite. To run it:
+
+1. Clone this repository.
+2. Install local workspace dependencies:
+   ```bash
+   npm install
+   ```
+3. Run the development server:
+   ```bash
+   npm run dev
+   ```
+4. Build the production package bundles:
+   ```bash
+   npm run build
+   ```
+
+---
+
+## Credits
+Built with ❤️ by [Ali Arshad](https://github.com/Ali-Arshad-110). Connect with me on [LinkedIn](https://www.linkedin.com/in/aliarshad110).
+
+## License
+This project is licensed under the [ISC License](LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,57 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+interface DevToolsDetectorOptions {
+    /** Keyboard shortcuts to intercept. Default covers common DevTools keys. */
+    blockedKeys?: string[];
+    /** Disable right-click context menu. Default: true */
+    disableRightClick?: boolean;
+    /** Disable text selection on the page. Default: true */
+    disableSelection?: boolean;
+    /** Called once when DevTools is first detected as open. */
+    onDetect?: () => void;
+    /** Called once when DevTools is detected as closed. */
+    onClose?: () => void;
+    /** Polling interval in ms. Default: 1500 */
+    pollInterval?: number;
+    /**
+     * Extra px added to both dimension thresholds.
+     * Raise this on layouts with large chrome (e.g. electron shells). Default: 0
+     */
+    thresholdBuffer?: number;
+}
+/**
+ * useDevToolsDetector
+
+ *
+ * Detects whether the browser's DevTools panel is open using three
+ * complementary heuristics:
+ *   1. Window outer/inner size differential (docked panel)
+ *   2. Console Image-getter trick (Chrome / Firefox console evaluation)
+ *   3. Optional debugger timing check (undocked panel, production only)
+ *
+ * Additionally provides keyboard-shortcut blocking and UX protections.
+ *
+ * @returns `true` when DevTools is considered open, `false` otherwise.
+ */
+declare function useDevToolsDetector(options?: DevToolsDetectorOptions): boolean;
+
+interface Props {
+    children: React.ReactNode;
+    overlay?: boolean;
+}
+declare const DevToolsProtection: ({ children, overlay, }: Props) => react_jsx_runtime.JSX.Element;
+
+interface DevToolsWarningOverlayProps {
+    /** Optional handler called when the user dismisses the overlay. */
+    onClose?: () => void;
+}
+/**
+ * DevToolsWarningOverlay
+ *
+ * Full-screen security overlay shown when DevTools are detected.
+ * Runs a 3-step animated scan sequence before revealing the warning card.
+ */
+declare const DevToolsWarningOverlay: React.FC<DevToolsWarningOverlayProps>;
+
+export { type DevToolsDetectorOptions, DevToolsProtection, DevToolsWarningOverlay, useDevToolsDetector };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+interface DevToolsDetectorOptions {
+    /** Keyboard shortcuts to intercept. Default covers common DevTools keys. */
+    blockedKeys?: string[];
+    /** Disable right-click context menu. Default: true */
+    disableRightClick?: boolean;
+    /** Disable text selection on the page. Default: true */
+    disableSelection?: boolean;
+    /** Called once when DevTools is first detected as open. */
+    onDetect?: () => void;
+    /** Called once when DevTools is detected as closed. */
+    onClose?: () => void;
+    /** Polling interval in ms. Default: 1500 */
+    pollInterval?: number;
+    /**
+     * Extra px added to both dimension thresholds.
+     * Raise this on layouts with large chrome (e.g. electron shells). Default: 0
+     */
+    thresholdBuffer?: number;
+}
+/**
+ * useDevToolsDetector
+
+ *
+ * Detects whether the browser's DevTools panel is open using three
+ * complementary heuristics:
+ *   1. Window outer/inner size differential (docked panel)
+ *   2. Console Image-getter trick (Chrome / Firefox console evaluation)
+ *   3. Optional debugger timing check (undocked panel, production only)
+ *
+ * Additionally provides keyboard-shortcut blocking and UX protections.
+ *
+ * @returns `true` when DevTools is considered open, `false` otherwise.
+ */
+declare function useDevToolsDetector(options?: DevToolsDetectorOptions): boolean;
+
+interface Props {
+    children: React.ReactNode;
+    overlay?: boolean;
+}
+declare const DevToolsProtection: ({ children, overlay, }: Props) => react_jsx_runtime.JSX.Element;
+
+interface DevToolsWarningOverlayProps {
+    /** Optional handler called when the user dismisses the overlay. */
+    onClose?: () => void;
+}
+/**
+ * DevToolsWarningOverlay
+ *
+ * Full-screen security overlay shown when DevTools are detected.
+ * Runs a 3-step animated scan sequence before revealing the warning card.
+ */
+declare const DevToolsWarningOverlay: React.FC<DevToolsWarningOverlayProps>;
+
+export { type DevToolsDetectorOptions, DevToolsProtection, DevToolsWarningOverlay, useDevToolsDetector };