🛡️ Secure Test Guard

A lightweight TypeScript library to protect web-based quizzes, exams, and assessments from common cheating methods.

✨ Features

| Feature | Description | |---------|-------------| | 🚫 Block Right-Click | Prevents context menu access | | ⌨️ Block DevTools Shortcuts | Blocks F12, Ctrl+Shift+I, etc. | | 🔐 Secret Toggle | Hidden shortcut for developers/testers | | 📺 Fullscreen Enforcer | Forces users to stay in fullscreen | | ⚙️ Fully Configurable | Customize everything | | 📦 Zero Dependencies | Lightweight and fast | | 🔷 TypeScript First | Full type support |

📦 Installation

npm install secure-test-guard

# secure-test-guard — Quick Reference

🚀 Quick Start

```typescript
import { initSecureTest } from 'secure-test-guard';

// Enable all protections with defaults
const secure = initSecureTest();

// Cleanup when done (e.g., on component unmount)
secure.destroyAll();

📖 Usage Examples

DevTools Guard Only

import { enableDevToolsGuard } from 'secure-test-guard';

const guard = enableDevToolsGuard({
  blockRightClick: true,
  blockShortcuts: true,
  blockF12: true,
  secretKey: { key: 'o', ctrlOrCmd: true, shift: true },
  onToggle: (isLocked) => {
    console.log(`Protection is ${isLocked ? 'ON' : 'OFF'}`);
  }
});

// Manual controls
guard.disable(); // Temporarily disable guard
guard.enable();  // Re-enable guard
guard.toggle();  // Toggle state
guard.isActive(); // Check current state
guard.destroy(); // Remove completely

Fullscreen Enforcer Only

import { enforceFullScreen } from 'secure-test-guard';

const fullscreen = enforceFullScreen({
  title: '📺 Fullscreen Required',
  message: 'Please enable fullscreen to continue your exam.',
  buttonText: 'Enter Fullscreen',
  theme: {
    backgroundColor: '#1e1e2e',
    textColor: '#cdd6f4',
    buttonColor: '#89b4fa',
    buttonTextColor: '#1e1e2e'
  },
  onFullscreenChange: (isFullscreen) => {
    if (!isFullscreen) {
      console.log('User exited fullscreen!');
    }
  }
});

// Manual controls
fullscreen.requestFullscreen(); // Enter fullscreen
fullscreen.exitFullscreen();    // Exit fullscreen
fullscreen.isFullscreen();      // Check status
fullscreen.destroy();           // Remove enforcer

Combined Usage (React Example)

import { useEffect } from 'react';
import { initSecureTest } from 'secure-test-guard';

function QuizPage() {
  useEffect(() => {
    const secure = initSecureTest({
      devTools: {
        blockRightClick: true,
        showAlerts: false,
        onToggle: (locked) => console.log('Guard:', locked)
      },
      fullscreen: {
        title: 'Quiz Mode',
        message: 'Fullscreen is required during the quiz.'
      }
    });

    return () => {
      secure.destroyAll();
    };
  }, []);

  return <div>Your Quiz Content</div>;
}

Disable Specific Feature

const secure = initSecureTest({
  devTools: {
    blockRightClick: true
  },
  fullscreen: false // Disable fullscreen enforcer
});

⌨️ Default Secret Shortcut

| Platform | Shortcut | |---------------|-----------------| | Windows/Linux | Ctrl + Shift + O | | macOS | Cmd + Shift + O |

This unlocks DevTools temporarily for testing/development.

🔧 API Reference

enableDevToolsGuard(options?)

Options

| Option | Type | Default | Description | |----------------------|----------|----------------------------------|--------------------------------------------| | blockRightClick | boolean | true | Block context menu | | blockShortcuts | boolean | true | Block DevTools shortcuts | | blockSave | boolean | true | Block Ctrl+S | | blockViewSource | boolean | true | Block Ctrl+U | | blockF12 | boolean | true | Block F12 key | | enableSecretToggle | boolean | true | Enable secret shortcut | | secretKey | object | { key: 'o', ctrlOrCmd: true, shift: true } | Secret key combo | | showAlerts | boolean | true | Show toggle alerts on toggle | | onToggle | function | - | Callback called when the guard toggles |

Notes:

• secretKey is an object describing the secret toggle combination. Example: { key: 'o', ctrlOrCmd: true, shift: true }.

enforceFullScreen(options?)

Options

| Option | Type | Default | Description | |------------------|----------|----------------------------------|--------------------------------------------| | title | string | '⚠️ Full Screen Required' | Overlay title | | message | string | '...' | Overlay message | | buttonText | string | 'ENABLE FULL SCREEN' | Button label | | theme | object | See below | Styling options (backgroundColor, textColor, buttonColor, buttonTextColor) | | delay | number | 0 | Delay before showing overlay (ms) | | onFullscreenChange| function| - | Status callback when fullscreen state changes |

Theme example:

{
  backgroundColor: '#1e1e2e',
  textColor: '#cdd6f4',
  buttonColor: '#89b4fa',
  buttonTextColor: '#1e1e2e'
}

⚠️ Important Notes

• The secret shortcut (default: Ctrl/Cmd + Shift + O) temporarily unlocks DevTools for testing/development. Use with caution in production environments.
• initSecureTest() returns an object with helpers for both devTools and fullscreen (depending on configuration). Use destroyAll() to clean up everything created by the instance.
• If you disable fullscreen by passing fullscreen: false, only the devTools guard will be active (if configured).

If you want this file committed to the repository (FrontifybyHB/collage-project), tell me the branch name and commit message and I can prepare the commit for you.