@asmitgh/proctoring-detector

Lightweight browser proctoring detector. Zero ML, zero dependencies — pure DOM event monitoring.

Detects and optionally blocks:

• Tab switches / window blur
• Fullscreen exits
• Copy / paste / cut
• Right-click / context menu
• DevTools shortcuts (F12, Ctrl+Shift+I/J/C, Ctrl+U/S)
• Screenshot keys (PrintScreen, macOS Cmd+Shift+3/4/5)
• Network going offline

Installation

npm install @asmitgh/proctoring-detector

Quick Start

import { getProctoringDetector } from "@asmitgh/proctoring-detector";

const detector = getProctoringDetector();

detector.start((violation) => {
  console.log(violation.type, violation.severity, violation.description);
  // Send to your API, update UI, etc.
});

// Later — cleanup
detector.stop();

Usage with React

import { useEffect } from "react";
import { getProctoringDetector, ProctoringViolation } from "@asmitgh/proctoring-detector";

export function ExamPage() {
  useEffect(() => {
    const detector = getProctoringDetector();

    detector.start((violation: ProctoringViolation) => {
      fetch("/api/proctoring/event", {
        method: "POST",
        body: JSON.stringify(violation),
      });
    });

    return () => detector.stop();
  }, []);

  return <div>Exam content</div>;
}

API

getProctoringDetector(): ProctoringDetector

Returns the singleton detector instance.

new ProctoringDetector()

Create a fresh instance (useful for testing).

detector.start(onViolation: ViolationCallback): void

Start monitoring. Attaches all event listeners.

detector.stop(): void

Stop monitoring. Removes all event listeners.

detector.getViolationCounts()

{
  tabSwitches: number;
  keyPresses: number;
  rightClicks: number;
  copyPastes: number;
}

Types

type ViolationType =
  | "TAB_SWITCH"
  | "WINDOW_BLUR"
  | "FULLSCREEN_EXIT"
  | "RIGHT_CLICK"
  | "PROHIBITED_KEY"
  | "COPY_PASTE"
  | "NETWORK_OFFLINE";

interface ProctoringViolation {
  type: ViolationType;
  description: string;
  timestamp: number;
  severity?: "LOW" | "MEDIUM" | "HIGH";
}

type ViolationCallback = (violation: ProctoringViolation) => void;

Severity Levels

| Severity | Examples | |----------|---------| | HIGH | Tab switch, window blur, fullscreen exit, copy/paste, devtools shortcuts | | MEDIUM | Right click | | LOW | Screenshot keys |

License

MIT © Asmit Ghosh