@tindalabs/shield 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,278 @@
+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;
+    /** Enable/disable clipboard protection (copy/cut/paste events + Clipboard API)
+     * @default false
+     */
+    preventClipboard?: boolean;
+    /** Clipboard protection options */
+    clipboardOptions?: ClipboardOptions;
+    /** 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?: boolean;
+    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?: boolean;
+    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;
+    }
+}
+export * from './assessment.js';

package/dist/types/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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 = {}));
+export * from './assessment.js';

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,44 @@
+import { SimpleLoggingService } from "../logging/simple/SimpleLoggingService";
+/**
+ * Abstract base for any component that owns a named, debug-toggleable logger.
+ *
+ * Consolidates the logger + debug-mode plumbing that was previously duplicated
+ * across {@link import("../../strategies/AbstractStrategy").AbstractStrategy},
+ * {@link import("../detectors/AbstractDevToolsDetector").AbstractDevToolsDetector},
+ * and {@link import("../../core/mediator/handlers/abstractEventHandler").AbstractEventHandler}.
+ *
+ * What lives here:
+ *   - `COMPONENT_NAME` (used as the log prefix and as an owner key in event-
+ *     manager / mediator subscriptions by subclasses).
+ *   - `debugMode` + `logger`, kept in sync.
+ *   - `log` / `warn` / `error` — thin pass-throughs to `SimpleLoggingService`,
+ *     which already debug-gates `log` and applies the brief-vs-verbose split on
+ *     `warn`. Subclasses' previous re-implementations of those gates were
+ *     redundant.
+ *
+ * What does NOT live here: error-classification helpers like `handleError` and
+ * `safeExecute` — `AbstractStrategy` and `AbstractDevToolsDetector` use
+ * different error-type enums (`StrategyErrorType` vs `DetectorErrorType`) and
+ * different reporting strategies, so hoisting them up would require generics
+ * that obscure the call sites for little gain. They stay in the subclasses.
+ */
+export declare abstract class LoggableComponent {
+    /** Used as the log prefix and as the owner key for event/mediator registrations. */
+    readonly COMPONENT_NAME: string;
+    protected debugMode: boolean;
+    protected logger: SimpleLoggingService;
+    constructor(componentName: string, debugMode?: boolean);
+    /**
+     * Toggle debug mode on both this component and its logger. Emits a
+     * confirmation line on enable (the disable case is silent because the logger
+     * is gated by the post-update flag).
+     */
+    setDebugMode(enabled: boolean): void;
+    isDebugEnabled(): boolean;
+    /** Debug log; suppressed in non-debug mode by `SimpleLoggingService`. */
+    protected log(message: string, ...args: unknown[]): void;
+    /** Warn log; brief form in non-debug mode (no args), full form with debug on. */
+    protected warn(message: string, ...args: unknown[]): void;
+    /** Error log; always printed. */
+    protected error(message: string, ...args: unknown[]): void;
+}

package/dist/utils/base/LoggableComponent.js

@@ -0,0 +1,56 @@
+import { SimpleLoggingService } from "../logging/simple/SimpleLoggingService";
+/**
+ * Abstract base for any component that owns a named, debug-toggleable logger.
+ *
+ * Consolidates the logger + debug-mode plumbing that was previously duplicated
+ * across {@link import("../../strategies/AbstractStrategy").AbstractStrategy},
+ * {@link import("../detectors/AbstractDevToolsDetector").AbstractDevToolsDetector},
+ * and {@link import("../../core/mediator/handlers/abstractEventHandler").AbstractEventHandler}.
+ *
+ * What lives here:
+ *   - `COMPONENT_NAME` (used as the log prefix and as an owner key in event-
+ *     manager / mediator subscriptions by subclasses).
+ *   - `debugMode` + `logger`, kept in sync.
+ *   - `log` / `warn` / `error` — thin pass-throughs to `SimpleLoggingService`,
+ *     which already debug-gates `log` and applies the brief-vs-verbose split on
+ *     `warn`. Subclasses' previous re-implementations of those gates were
+ *     redundant.
+ *
+ * What does NOT live here: error-classification helpers like `handleError` and
+ * `safeExecute` — `AbstractStrategy` and `AbstractDevToolsDetector` use
+ * different error-type enums (`StrategyErrorType` vs `DetectorErrorType`) and
+ * different reporting strategies, so hoisting them up would require generics
+ * that obscure the call sites for little gain. They stay in the subclasses.
+ */
+export class LoggableComponent {
+    constructor(componentName, debugMode = false) {
+        this.COMPONENT_NAME = componentName;
+        this.debugMode = debugMode;
+        this.logger = new SimpleLoggingService(componentName, debugMode);
+    }
+    /**
+     * Toggle debug mode on both this component and its logger. Emits a
+     * confirmation line on enable (the disable case is silent because the logger
+     * is gated by the post-update flag).
+     */
+    setDebugMode(enabled) {
+        this.debugMode = enabled;
+        this.logger.setDebugMode(enabled);
+        this.logger.log(`Debug mode ${enabled ? "enabled" : "disabled"}`);
+    }
+    isDebugEnabled() {
+        return this.debugMode;
+    }
+    /** Debug log; suppressed in non-debug mode by `SimpleLoggingService`. */
+    log(message, ...args) {
+        this.logger.log(message, ...args);
+    }
+    /** Warn log; brief form in non-debug mode (no args), full form with debug on. */
+    warn(message, ...args) {
+        this.logger.warn(message, ...args);
+    }
+    /** Error log; always printed. */
+    error(message, ...args) {
+        this.logger.error(message, ...args);
+    }
+}

package/dist/utils/detectors/AbstractDevToolsDetector.d.ts

@@ -0,0 +1,98 @@
+import type { DevToolsDetector, DevToolsDetectorOptions } from "./detectorInterface";
+import { LoggableComponent } from "../base/LoggableComponent";
+/**
+ * Enum representing different types of errors that can occur in detectors
+ */
+export declare enum DetectorErrorType {
+    /**
+     * Error during initialization of a detector
+     */
+    INITIALIZATION_ERROR = "initialization_error",
+    /**
+     * Error during detection check
+     */
+    DETECTION_ERROR = "detection_error",
+    /**
+     * Error related to browser compatibility
+     */
+    COMPATIBILITY_ERROR = "compatibility_error",
+    /**
+     * Error during cleanup/disposal
+     */
+    DISPOSAL_ERROR = "disposal_error",
+    /**
+     * Error in worker communication
+     */
+    WORKER_ERROR = "worker_error",
+    /**
+     * Error in DOM manipulation
+     */
+    DOM_ERROR = "dom_error",
+    /**
+     * Error in event handling
+     */
+    EVENT_ERROR = "event_error",
+    /**
+     * Unexpected or unknown error
+     */
+    UNKNOWN_ERROR = "unknown_error"
+}
+/**
+ * Abstract base class for DevTools detectors
+ * Implements common functionality to reduce duplication across detector implementations
+ */
+export declare abstract class AbstractDevToolsDetector extends LoggableComponent implements DevToolsDetector {
+    protected readonly detectorName: string;
+    protected isDevToolsOpen: boolean;
+    protected isChecking: boolean;
+    protected onDevToolsChange: (isOpen: boolean) => void;
+    /**
+     * Create a new detector instance
+     * @param detectorName Name of the detector for logging
+     * @param options Configuration options
+     */
+    constructor(detectorName: string, options?: DevToolsDetectorOptions);
+    /**
+     * Check if DevTools is open
+     * This method must be implemented by subclasses
+     */
+    abstract checkDevTools(): void;
+    /**
+     * Get the current DevTools state
+     * @returns True if DevTools is open
+     */
+    isOpen(): boolean;
+    /**
+     * Update the DevTools state and notify listeners if changed
+     * @param isOpen New DevTools state
+     */
+    protected updateDevToolsState(isOpen: boolean): void;
+    /**
+     * Handle an error with appropriate logging
+     * @param errorType Type of error that occurred
+     * @param message Error message
+     * @param error The error object
+     */
+    protected handleError(errorType: DetectorErrorType, message: string, error: unknown): void;
+    /**
+     * Execute a function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error to report if the operation fails
+     * @param fn Function to execute
+     * @returns The result of the function or undefined if an error occurred
+     */
+    protected safeExecute<T>(operation: string, errorType: DetectorErrorType, fn: () => T): T | undefined;
+    /**
+     * Execute an async function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error to report if the operation fails
+     * @param fn Async function to execute
+     * @returns Promise resolving to the result of the function or undefined if an error occurred
+     */
+    protected safeExecuteAsync<T>(operation: string, errorType: DetectorErrorType, fn: () => Promise<T>): Promise<T | undefined>;
+    /**
+     * Clean up resources
+     * Override in subclasses to perform detector-specific cleanup
+     */
+    dispose(): void;
+}