content-security-toolkit 1.0.0

package/dist/strategies/index.d.ts

@@ -0,0 +1,9 @@
+export * from './KeyboardStrategy';
+export * from './ContextMenuStrategy';
+export * from './PrintStrategy';
+export * from './WatermarkStrategy';
+export * from './SelectionStrategy';
+export * from './DevToolsStrategy';
+export * from './ScreenshotStrategy';
+export * from './ExtensionStrategy';
+export * from './IFrameStrategy';

package/dist/strategies/index.js

@@ -0,0 +1,10 @@
+// BARREL FILE
+export * from './KeyboardStrategy';
+export * from './ContextMenuStrategy';
+export * from './PrintStrategy';
+export * from './WatermarkStrategy';
+export * from './SelectionStrategy';
+export * from './DevToolsStrategy';
+export * from './ScreenshotStrategy';
+export * from './ExtensionStrategy';
+export * from './IFrameStrategy';

package/dist/types/index.d.ts

@@ -0,0 +1,271 @@
+import { OverlayOptions } from "@/utils/securityOverlayManager";
+/**
+ * Configuration options for content protection
+ */
+export interface ContentProtectionOptions {
+    /** Enable/disable keyboard shortcuts protection */
+    preventKeyboardShortcuts?: boolean;
+    /** Enable/disable context menu protection */
+    preventContextMenu?: boolean;
+    /** Context menu protection options */
+    contextMenuOptions?: ContextMenuOptions;
+    /** Enable/disable print protection */
+    preventPrinting?: boolean;
+    /** Enable/disable selection protection */
+    preventSelection?: boolean;
+    /** Enable/disable watermarking */
+    enableWatermark?: boolean;
+    /** Enable/disable DevTools detection */
+    preventDevTools?: boolean;
+    /** Dev tools protection options */
+    devToolsOptions?: DevToolsOptions;
+    /** Enable/disable screenshot protection */
+    preventScreenshots?: boolean;
+    /** Screenshot protection options */
+    screenshotOptions?: ScreenshotOptions;
+    /** Watermark options */
+    watermarkOptions?: WatermarkOptions;
+    /** Enable/disable scraping extension protection */
+    preventExtensions?: boolean;
+    /** Extension protection options */
+    extensionOptions?: BrowserExtensionOptions;
+    /** Enable/disable iFrame protection */
+    preventEmbedding?: boolean;
+    /** iFrame protection options */
+    frameEmbeddingOptions?: FrameEmbeddingOptions;
+    /** Target element (defaults to document.body) */
+    targetElement?: HTMLElement | null;
+    /** Custom event handlers */
+    customHandlers?: CustomEventHandlers;
+    /** Enable debug mode for all strategies
+    * @default false
+    */
+    debugMode?: boolean;
+}
+/**
+ * Watermark configuration options
+ */
+export interface WatermarkOptions {
+    /** Text to display in watermark */
+    text: string;
+    /** User identifier to include in watermark */
+    userId?: string;
+    /** Opacity of watermark (0-1) */
+    opacity?: number;
+    /** Density of watermark pattern (1-10) */
+    density?: number;
+    /** Custom styling for watermark */
+    style?: Partial<CSSStyleDeclaration>;
+}
+export interface ContextMenuOptions {
+    /**
+     * Whether to observe and protect iframes that are dynamically added to the DOM
+     * @default false
+     */
+    observeForIframes?: boolean;
+}
+/**
+ * Clipboard protection options
+ */
+export interface ClipboardOptions {
+    /**
+     * Whether to prevent copy operations
+     * @default true
+     */
+    preventCopy?: boolean;
+    /**
+     * Whether to prevent cut operations
+     * @default true
+     */
+    preventCut?: boolean;
+    /**
+     * Whether to prevent paste operations
+     * @default false
+     */
+    preventPaste?: boolean;
+    /**
+     * Text to replace copied content with
+     * @default "Content copying is disabled for security reasons."
+     */
+    replacementText?: string;
+}
+/**
+ * Screenshot protection overlay options
+ */
+export interface ScreenshotOptions {
+    /**
+     * Whether to show overlay when triggered
+     * @default true
+     */
+    showOverlay?: boolean;
+    overlayOptions?: OverlayOptions;
+    /**
+     * Whether to hide sensitive content when triggered
+     * @default true
+     */
+    hideContent?: boolean;
+    /**
+    * Whether to prevent fullscreen mode
+    * @default true
+    */
+    preventFullscreen?: boolean;
+    /**
+     * Message to display when fullscreen is attempted
+     */
+    fullscreenMessage?: string;
+}
+/**
+ * Options for the DevTools protection overlay
+ */
+export interface DevToolsOptions {
+    /**
+    * Check frequency in milliseconds
+    */
+    checkFrequency?: number;
+    /**
+     * Whether to show overlay when triggered
+     * @default true
+     */
+    showOverlay?: boolean;
+    overlayOptions?: OverlayOptions;
+    /**
+     * Whether to hide sensitive content when triggered
+     * @default true
+     */
+    hideContent?: boolean;
+    /**
+    * Specific detector types to use
+    * If empty, will use the optimal detectors for the current browser
+    */
+    detectorTypes?: string[];
+}
+export interface BrowserExtensionOptions {
+    configPath?: string;
+    extensionsConfig?: Record<string, ExtensionConfig>;
+    detectionInterval?: number;
+    /**
+     * Whether to show overlay when triggered
+     * @default true
+     */
+    showOverlay: true;
+    overlayOptions?: OverlayOptions;
+    /**
+     * Whether to hide sensitive content when triggered
+     * @default true
+     */
+    hideContent?: boolean;
+}
+/**
+ * Configuration for a specific browser extension to detect
+ */
+export interface ExtensionConfig {
+    name: string;
+    description?: string;
+    risk: string;
+    detectionMethods: {
+        domSelectors?: string[];
+        jsSignatures?: string[];
+    };
+}
+/**
+ * Options for the FrameEmbeddingProtectionStrategy
+ */
+export interface FrameEmbeddingOptions {
+    /**
+     * Whether to show overlay when triggered
+     * @default true
+     */
+    showOverlay: true;
+    overlayOptions?: OverlayOptions;
+    /**
+    * Whether to hide sensitive content when triggered
+    * @default true
+    */
+    hideContent?: boolean;
+    /**
+     * Allowed domains that can embed the content (empty array means only same-origin is allowed)
+     */
+    allowedDomains?: string[];
+    /**
+     * Whether to completely block the content from loading in any iframe (even same-origin)
+     */
+    blockAllFrames?: boolean;
+}
+/**
+ * Custom event handlers
+ */
+export interface CustomEventHandlers {
+    /** Called when protection is bypassed */
+    onProtectionBypassed?: (method: string, event: Event) => void;
+    /** Called when print is attempted */
+    onPrintAttempt?: (event: Event) => void;
+    /** Called when keyboard shortcut is blocked */
+    onKeyboardShortcutBlocked?: (event: KeyboardEvent) => void;
+    /** Called when DevTools is opened or closed */
+    onDevToolsOpen?: (isOpen: boolean) => void;
+    /** Called when a clipboard operation is detected */
+    onClipboardAttempt?: (event: Event, action: "copy" | "cut" | "paste") => void;
+    onContextMenuAttempt?: (event: Event) => void;
+    onSelectionAttempt?: (event: Event) => void;
+    onScreenshotAttempt?: (event: Event) => void;
+    onExtensionDetected?: (extensionId: string, extensionName: string, riskLevel: "low" | "medium" | "high") => void;
+    onFrameEmbeddingDetected?: (isEmbedded: boolean, isExternalFrame: boolean) => void;
+    /**
+     * Called when content is hidden due to a security event (e.g., DevTools opened)
+     * @param reason The reason why content was hidden
+     * @param targetElement The element whose content was hidden
+     */
+    onContentHidden?: (reason: string, targetElement: HTMLElement | null) => void;
+    /**
+     * Called when content is restored after a security event clears (e.g., DevTools closed)
+     * Useful for frameworks like Vue to re-mount components after innerHTML restoration
+     * @param targetElement The element whose content was restored
+     */
+    onContentRestored?: (targetElement: HTMLElement | null) => void;
+}
+/**
+ * Protection strategy interface
+ */
+export interface ProtectionStrategy {
+    /**
+    * Unique identifier for the strategy
+    * Used for logging and event management
+    */
+    readonly STRATEGY_NAME: string;
+    /** Apply the protection strategy */
+    apply(options?: unknown): void;
+    /** Remove the protection strategy */
+    remove(): void;
+    /** Check if strategy is currently applied */
+    isApplied(): boolean;
+    /** Update strategy options */
+    updateOptions(options: Record<string, unknown>): void;
+    /** Get the debug mode status
+    * @returns True if debug mode is enabled
+    */
+    isDebugEnabled(): boolean;
+    /** Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled: boolean): void;
+}
+/**
+ * Protection strategy names
+ */
+export declare enum StrategyName {
+    KEYBOARD = "KeyboardStrategy",
+    CONTEXT_MENU = "ContextMenuStrategy",
+    PRINT = "PrintStrategy",
+    SELECTION = "SelectionStrategy",
+    WATERMARK = "WatermarkStrategy",
+    DEV_TOOLS = "DevToolsStrategy",
+    SCREENSHOT = "ScreenshotStrategy",
+    BROWSER_EXTENSION = "BrowserExtensionStrategy",
+    FRAME_EMBEDDING = "FrameEmbeddingStrategy",
+    CLIPBOARD = "ClipboardStrategy"
+}
+declare global {
+    interface Console {
+        exception?: (...data: unknown[]) => void;
+    }
+}

package/dist/types/index.js

@@ -0,0 +1,16 @@
+/**
+ * Protection strategy names
+ */
+export var StrategyName;
+(function (StrategyName) {
+    StrategyName["KEYBOARD"] = "KeyboardStrategy";
+    StrategyName["CONTEXT_MENU"] = "ContextMenuStrategy";
+    StrategyName["PRINT"] = "PrintStrategy";
+    StrategyName["SELECTION"] = "SelectionStrategy";
+    StrategyName["WATERMARK"] = "WatermarkStrategy";
+    StrategyName["DEV_TOOLS"] = "DevToolsStrategy";
+    StrategyName["SCREENSHOT"] = "ScreenshotStrategy";
+    StrategyName["BROWSER_EXTENSION"] = "BrowserExtensionStrategy";
+    StrategyName["FRAME_EMBEDDING"] = "FrameEmbeddingStrategy";
+    StrategyName["CLIPBOARD"] = "ClipboardStrategy";
+})(StrategyName || (StrategyName = {}));

package/dist/utils/DOMObserver.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Options for the DOM observer
+ */
+export interface DomObserverOptions {
+    /**
+     * Target element to observe
+     */
+    targetElement: HTMLElement;
+    /**
+     * Callback function when elements are removed
+     */
+    onElementsRemoved?: (removedElements: HTMLElement[]) => void;
+    /**
+     * Callback function when elements are added
+     */
+    onElementsAdded?: (addedElements: HTMLElement[]) => void;
+    /**
+     * Elements to watch for removal
+     */
+    elementsToWatch: HTMLElement[];
+    /**
+     * Whether to observe child elements as well
+     */
+    observeSubtree?: boolean;
+    /**
+     * Enable debug mode for troubleshooting
+     */
+    debugMode?: boolean;
+    /**
+     * Custom name for logging
+     */
+    name?: string;
+}
+/**
+ * Helper class to observe DOM changes and detect when specific elements are added or removed
+ */
+export declare class DomObserver {
+    private observer;
+    private options;
+    private isObserving;
+    /**
+     * Create a new DOM observer
+     * @param options Observer options
+     */
+    constructor(options: DomObserverOptions);
+    /**
+     * Start observing the DOM for changes
+     */
+    startObserving(): void;
+    /**
+     * Stop observing the DOM
+     */
+    stopObserving(): void;
+    /**
+     * Update the elements to watch
+     * @param elements New elements to watch
+     */
+    updateElementsToWatch(elements: HTMLElement[]): void;
+    /**
+     * Update the target element
+     * @param element New target element
+     */
+    updateTargetElement(element: HTMLElement): void;
+    /**
+     * Check if the observer is currently observing
+     */
+    isActive(): boolean;
+}

package/dist/utils/DOMObserver.js

@@ -0,0 +1,134 @@
+/**
+ * Helper class to observe DOM changes and detect when specific elements are added or removed
+ */
+export class DomObserver {
+    /**
+     * Create a new DOM observer
+     * @param options Observer options
+     */
+    constructor(options) {
+        this.observer = null;
+        this.isObserving = false;
+        this.options = {
+            observeSubtree: true,
+            debugMode: false,
+            name: 'DomObserver',
+            ...options,
+        };
+    }
+    /**
+     * Start observing the DOM for changes
+     */
+    startObserving() {
+        if (this.isObserving || typeof MutationObserver === 'undefined' || !this.options.targetElement) {
+            return;
+        }
+        // Remove any existing observer
+        this.stopObserving();
+        // Create a new observer
+        this.observer = new MutationObserver((mutations) => {
+            const removedElements = [];
+            const addedElements = [];
+            for (const mutation of mutations) {
+                if (mutation.type === 'childList') {
+                    // Check if any of our watched elements were removed
+                    for (const node of Array.from(mutation.removedNodes)) {
+                        if (node instanceof HTMLElement) {
+                            if (this.options.elementsToWatch.includes(node)) {
+                                removedElements.push(node);
+                                if (this.options.debugMode) {
+                                    console.log(`${this.options.name}: Watched element was removed from DOM`, node);
+                                }
+                            }
+                        }
+                    }
+                    // Check for added nodes if we have an onElementsAdded callback
+                    if (this.options.onElementsAdded) {
+                        for (const node of Array.from(mutation.addedNodes)) {
+                            if (node instanceof HTMLElement) {
+                                addedElements.push(node);
+                                // If we're observing the subtree, also check for child elements
+                                if (this.options.observeSubtree) {
+                                    const childElements = node.querySelectorAll("*");
+                                    childElements.forEach((child) => {
+                                        if (child instanceof HTMLElement) {
+                                            addedElements.push(child);
+                                        }
+                                    });
+                                }
+                                if (this.options.debugMode) {
+                                    console.log(`${this.options.name}: Element was added to DOM`, node);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Call callbacks if we have elements to report
+            if (removedElements.length > 0 && this.options.onElementsRemoved) {
+                this.options.onElementsRemoved(removedElements);
+            }
+            if (addedElements.length > 0 && this.options.onElementsAdded) {
+                this.options.onElementsAdded(addedElements);
+            }
+        });
+        // Start observing the target element
+        this.observer.observe(this.options.targetElement, {
+            childList: true,
+            subtree: this.options.observeSubtree,
+        });
+        this.isObserving = true;
+        if (this.options.debugMode) {
+            console.log(`${this.options.name}: Started observing`, {
+                target: this.options.targetElement,
+                elementsCount: this.options.elementsToWatch.length,
+                subtree: this.options.observeSubtree,
+            });
+        }
+    }
+    /**
+     * Stop observing the DOM
+     */
+    stopObserving() {
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+            this.isObserving = false;
+            if (this.options.debugMode) {
+                console.log(`${this.options.name}: Stopped observing`);
+            }
+        }
+    }
+    /**
+     * Update the elements to watch
+     * @param elements New elements to watch
+     */
+    updateElementsToWatch(elements) {
+        this.options.elementsToWatch = elements;
+        if (this.isObserving && this.options.debugMode) {
+            console.log(`${this.options.name}: Updated elements to watch`, {
+                elementsCount: elements.length,
+            });
+        }
+    }
+    /**
+     * Update the target element
+     * @param element New target element
+     */
+    updateTargetElement(element) {
+        if (this.options.targetElement !== element) {
+            this.options.targetElement = element;
+            // Restart observing with the new target
+            if (this.isObserving) {
+                this.stopObserving();
+                this.startObserving();
+            }
+        }
+    }
+    /**
+     * Check if the observer is currently observing
+     */
+    isActive() {
+        return this.isObserving;
+    }
+}

package/dist/utils/base/LoggableComponent.d.ts

@@ -0,0 +1,62 @@
+import { SimpleLoggingService } from "../logging/simple/SimpleLoggingService";
+/**
+ * Base class providing common logging and error handling functionality.
+ * Extract shared functionality from AbstractStrategy, AbstractDevToolsDetector, and AbstractEventHandler.
+ */
+export declare abstract class LoggableComponent {
+    readonly COMPONENT_NAME: string;
+    protected debugMode: boolean;
+    protected logger: SimpleLoggingService;
+    /**
+     * Create a new LoggableComponent
+     * @param componentName Unique name for the component (used in logging)
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(componentName: string, debugMode?: boolean);
+    /**
+     * Get the debug mode status
+     * @returns True if debug mode is enabled
+     */
+    isDebugEnabled(): boolean;
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Log a debug message if debug mode is enabled
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    protected log(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    protected warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    protected error(message: string, ...args: unknown[]): void;
+    /**
+     * Execute a function with error handling
+     * This method can be overridden in subclasses to add type-specific error handling.
+     * @param operation Name of the operation for error reporting
+     * @param errorTypeOrFn Either an error type (for subclasses) or the function to execute
+     * @param fn Function to execute (only if errorTypeOrFn is an error type)
+     * @returns The result of the function or undefined if an error occurred
+     */
+    protected safeExecute<T>(operation: string, errorTypeOrFn: unknown, fn?: () => T): T | undefined;
+    /**
+     * Execute an async function with error handling
+     * This method can be overridden in subclasses to add type-specific error handling.
+     * @param operation Name of the operation for error reporting
+     * @param errorTypeOrFn Either an error type (for subclasses) or the async function to execute
+     * @param fn Async function to execute (only if errorTypeOrFn is an error type)
+     * @returns Promise resolving to the result of the function or undefined if an error occurred
+     */
+    protected safeExecuteAsync<T>(operation: string, errorTypeOrFn: unknown, fn?: () => Promise<T>): Promise<T | undefined>;
+}

package/dist/utils/base/LoggableComponent.js

@@ -0,0 +1,95 @@
+import { SimpleLoggingService } from "../logging/simple/SimpleLoggingService";
+/**
+ * Base class providing common logging and error handling functionality.
+ * Extract shared functionality from AbstractStrategy, AbstractDevToolsDetector, and AbstractEventHandler.
+ */
+export class LoggableComponent {
+    /**
+     * Create a new LoggableComponent
+     * @param componentName Unique name for the component (used in logging)
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(componentName, debugMode = false) {
+        this.COMPONENT_NAME = componentName;
+        this.debugMode = debugMode;
+        this.logger = new SimpleLoggingService(componentName, debugMode);
+    }
+    /**
+     * Get the debug mode status
+     * @returns True if debug mode is enabled
+     */
+    isDebugEnabled() {
+        return this.debugMode;
+    }
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled) {
+        this.debugMode = enabled;
+        this.logger.setDebugMode(enabled);
+        this.logger.log(`Debug mode ${enabled ? "enabled" : "disabled"}`);
+    }
+    /**
+     * Log a debug message if debug mode is enabled
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    log(message, ...args) {
+        this.logger.log(message, ...args);
+    }
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    warn(message, ...args) {
+        this.logger.warn(message, ...args);
+    }
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    error(message, ...args) {
+        this.logger.error(message, ...args);
+    }
+    /**
+     * Execute a function with error handling
+     * This method can be overridden in subclasses to add type-specific error handling.
+     * @param operation Name of the operation for error reporting
+     * @param errorTypeOrFn Either an error type (for subclasses) or the function to execute
+     * @param fn Function to execute (only if errorTypeOrFn is an error type)
+     * @returns The result of the function or undefined if an error occurred
+     */
+    safeExecute(operation, errorTypeOrFn, fn) {
+        // If only two args were provided (operation, fn), fn is actually in errorTypeOrFn
+        const actualFn = fn || errorTypeOrFn;
+        try {
+            return actualFn();
+        }
+        catch (error) {
+            this.logger.error(`Error during ${operation}:`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Execute an async function with error handling
+     * This method can be overridden in subclasses to add type-specific error handling.
+     * @param operation Name of the operation for error reporting
+     * @param errorTypeOrFn Either an error type (for subclasses) or the async function to execute
+     * @param fn Async function to execute (only if errorTypeOrFn is an error type)
+     * @returns Promise resolving to the result of the function or undefined if an error occurred
+     */
+    async safeExecuteAsync(operation, errorTypeOrFn, fn) {
+        // If only two args were provided (operation, fn), fn is actually in errorTypeOrFn
+        const actualFn = fn || errorTypeOrFn;
+        try {
+            return await actualFn();
+        }
+        catch (error) {
+            this.logger.error(`Error during ${operation}:`, error);
+            return undefined;
+        }
+    }
+}

package/dist/utils/debuggerDetector/debuggerDetectionWorker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Worker script for DevTools detection
+ * This worker helps detect DevTools by using the debugger statement
+ * in a separate thread, which won't block the main UI thread
+ */
+export type DebuggerDetectionWorker = typeof self;