@tindalabs/shield 0.1.0

package/dist/core/mediator/ContentProtectionMediator.js

@@ -0,0 +1,238 @@
+/**
+ * Mediator for coordinating communication between protection strategies
+ * Implements the mediator pattern to decouple strategies and enable event-based communication
+ */
+export class ContentProtectionMediator {
+    /**
+     * Create a new ContentProtectionMediator
+     * @param debugMode Enable debug mode for detailed logging
+     */
+    constructor(debugMode = false) {
+        this.subscriptions = new Map();
+        this.subscriptionCounter = 0;
+        this.eventHistory = [];
+        this.MAX_HISTORY_SIZE = 100;
+        this.debugMode = debugMode;
+        if (this.debugMode) {
+            console.log('ContentProtectionMediator: Initialized');
+        }
+    }
+    /**
+     * Subscribe to an event
+     * @param eventType Type of event to subscribe to
+     * @param handler Handler function for the event
+     * @param options Optional subscription options
+     * @returns Subscription ID for later unsubscribing
+     */
+    subscribe(eventType, handler, options) {
+        if (!handler || typeof handler !== 'function') {
+            console.error('ContentProtectionMediator: Invalid handler provided to subscribe');
+            return '';
+        }
+        // Generate a unique subscription ID
+        const subscriptionId = `sub_${++this.subscriptionCounter}`;
+        // Create the subscription object
+        const subscription = {
+            id: subscriptionId,
+            eventType,
+            handler,
+            filter: options?.filter,
+            priority: options?.priority || 0,
+            context: options?.context
+        };
+        // Get or create the array of subscriptions for this event type
+        if (!this.subscriptions.has(eventType)) {
+            this.subscriptions.set(eventType, []);
+        }
+        // Add the subscription to the array
+        const subscriptionsForType = this.subscriptions.get(eventType);
+        subscriptionsForType.push(subscription);
+        // Sort by priority (higher numbers first)
+        subscriptionsForType.sort((a, b) => (b.priority || 0) - (a.priority || 0));
+        if (this.debugMode) {
+            console.log(`ContentProtectionMediator: Subscribed to ${eventType} with ID ${subscriptionId}`, options ? `(priority: ${options.priority || 0}, context: ${options.context || 'none'})` : '');
+        }
+        return subscriptionId;
+    }
+    /**
+     * Unsubscribe from an event
+     * @param subscriptionId ID of the subscription to remove
+     * @returns True if the subscription was found and removed
+     */
+    unsubscribe(subscriptionId) {
+        if (!subscriptionId)
+            return false;
+        let found = false;
+        // Check all event types
+        for (const [eventType, subscriptions] of this.subscriptions.entries()) {
+            const initialLength = subscriptions.length;
+            // Filter out the subscription with the given ID
+            const filteredSubscriptions = subscriptions.filter(sub => sub.id !== subscriptionId);
+            if (filteredSubscriptions.length < initialLength) {
+                // We found and removed the subscription
+                this.subscriptions.set(eventType, filteredSubscriptions);
+                found = true;
+                if (this.debugMode) {
+                    console.log(`ContentProtectionMediator: Unsubscribed from ${eventType} with ID ${subscriptionId}`);
+                }
+                break;
+            }
+        }
+        return found;
+    }
+    /**
+     * Unsubscribe all handlers with a specific context
+     * @param context Context to unsubscribe (e.g., strategy name)
+     * @returns Number of subscriptions removed
+     */
+    unsubscribeByContext(context) {
+        if (!context)
+            return 0;
+        let removedCount = 0;
+        // Check all event types
+        for (const [eventType, subscriptions] of this.subscriptions.entries()) {
+            const initialLength = subscriptions.length;
+            // Filter out subscriptions with the given context
+            const filteredSubscriptions = subscriptions.filter(sub => sub.context !== context);
+            if (filteredSubscriptions.length < initialLength) {
+                // We found and removed subscriptions
+                const removed = initialLength - filteredSubscriptions.length;
+                removedCount += removed;
+                this.subscriptions.set(eventType, filteredSubscriptions);
+                if (this.debugMode) {
+                    console.log(`ContentProtectionMediator: Unsubscribed ${removed} handlers for ${context} from ${eventType}`);
+                }
+            }
+        }
+        return removedCount;
+    }
+    /**
+     * Publish an event to all subscribers
+     * @param event Event to publish
+     */
+    publish(event) {
+        console.log('Publishing event', event);
+        if (!event || !event.type) {
+            console.error('ContentProtectionMediator: Invalid event provided to publish');
+            return;
+        }
+        // Add timestamp if not provided
+        if (!event.timestamp) {
+            event.timestamp = Date.now();
+        }
+        // Store in history for debugging
+        this.addToEventHistory(event);
+        // Get subscriptions for this event type
+        const subscriptions = this.subscriptions.get(event.type) || [];
+        if (subscriptions.length === 0) {
+            if (this.debugMode) {
+                console.log(`ContentProtectionMediator: No subscribers for ${event.type}`);
+            }
+            return;
+        }
+        if (this.debugMode) {
+            console.log(`ContentProtectionMediator: Publishing ${event.type} from ${event.source}`, event.data ? `with data: ${JSON.stringify(event.data)}` : '');
+        }
+        // Call each handler
+        for (const subscription of subscriptions) {
+            try {
+                // Apply filter if provided
+                if (subscription.filter && !subscription.filter(event)) {
+                    continue;
+                }
+                // Call the handler
+                subscription.handler(event);
+            }
+            catch (error) {
+                console.error(`ContentProtectionMediator: Error in handler for ${event.type}:`, error);
+            }
+        }
+    }
+    /**
+     * Get all subscriptions for a specific event type
+     * @param eventType Type of event to get subscriptions for
+     * @returns Array of subscriptions
+     */
+    getSubscriptions(eventType) {
+        return [...(this.subscriptions.get(eventType) || [])];
+    }
+    /**
+     * Get all subscriptions
+     * @returns Map of event types to subscriptions
+     */
+    getAllSubscriptions() {
+        // Return a deep copy to prevent external modification
+        const result = new Map();
+        for (const [eventType, subscriptions] of this.subscriptions.entries()) {
+            result.set(eventType, [...subscriptions]);
+        }
+        return result;
+    }
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled) {
+        this.debugMode = enabled;
+        if (this.debugMode) {
+            console.log('ContentProtectionMediator: Debug mode enabled');
+        }
+    }
+    /**
+     * Get debug information about the mediator
+     * @returns Object with debug information
+     */
+    getDebugInfo() {
+        let totalSubscriptions = 0;
+        for (const subscriptions of this.subscriptions.values()) {
+            totalSubscriptions += subscriptions.length;
+        }
+        return {
+            subscriptionCount: totalSubscriptions,
+            eventTypeCount: this.subscriptions.size,
+            eventTypes: Array.from(this.subscriptions.keys()),
+            recentEvents: [...this.eventHistory]
+        };
+    }
+    /**
+     * Add an event to the history
+     * @param event Event to add
+     */
+    addToEventHistory(event) {
+        this.eventHistory.unshift(event);
+        // Limit history size
+        if (this.eventHistory.length > this.MAX_HISTORY_SIZE) {
+            this.eventHistory.pop();
+        }
+    }
+    /**
+     * Clear all subscriptions
+     * @returns Number of subscriptions cleared
+     */
+    clearAllSubscriptions() {
+        let count = 0;
+        for (const subscriptions of this.subscriptions.values()) {
+            count += subscriptions.length;
+        }
+        this.subscriptions.clear();
+        if (this.debugMode) {
+            console.log(`ContentProtectionMediator: Cleared ${count} subscriptions`);
+        }
+        return count;
+    }
+    /**
+     * Helper method to create and publish an event
+     * @param type Event type
+     * @param source Source of the event
+     * @param data Additional data
+     */
+    createAndPublishEvent(type, source, data) {
+        const event = {
+            type,
+            source,
+            timestamp: Date.now(),
+            data
+        };
+        this.publish(event);
+    }
+}

package/dist/core/mediator/eventDataTypes.d.ts

@@ -0,0 +1,112 @@
+import { OverlayOptions } from "@/utils/securityOverlayManager";
+import { ProtectionEventType } from "./protection-event";
+import { PlaceholderOptions } from "@/utils/protectedContentManager";
+import { ExtensionConfig } from "@/types";
+/**
+ * Interface defining the data structure for each event type.
+ *
+ * Keep this in sync with the {@link ProtectionEventType} enum — every value
+ * in the enum should have a matching `[ProtectionEventType.X]: { ... }` entry
+ * here. The trailing index signature catches any drift (and lets ad-hoc
+ * subscribers attach handlers for not-yet-typed events without compile errors).
+ */
+export interface EventDataMap {
+    [ProtectionEventType.DEVTOOLS_STATE_CHANGE]: {
+        isOpen: boolean;
+        target?: HTMLElement | null;
+        showOverlay?: boolean | null;
+        overlayOptions?: OverlayOptions | null;
+        hideContent?: boolean | null;
+    };
+    [ProtectionEventType.EXTENSION_DETECTED]: {
+        extension: ExtensionConfig | null;
+        showOverlay?: boolean | null;
+        overlayOptions?: OverlayOptions | null;
+        hideContent?: boolean | null;
+        priority: number;
+        reason: string;
+        target?: HTMLElement | null;
+    };
+    [ProtectionEventType.SCREENSHOT_ATTEMPT]: {
+        showOverlay?: boolean | null;
+        hideContent?: boolean | null;
+        overlayOptions?: OverlayOptions | null;
+        duration?: number | null;
+        priority: number;
+        reason: string;
+        target?: HTMLElement | null;
+    };
+    [ProtectionEventType.FRAME_EMBEDDING_DETECTED]: {
+        isEmbedded: boolean;
+        isExternalFrame: boolean;
+        parentDomain?: string;
+        targetElement?: HTMLElement | null;
+        showOverlay?: boolean | null;
+        hideContent?: boolean | null;
+        overlayOptions?: OverlayOptions | null;
+    };
+    [ProtectionEventType.CONTENT_HIDDEN]: {
+        strategyName: string;
+        reason: string;
+        options: PlaceholderOptions;
+        targetElement?: HTMLElement | null;
+        priority: number;
+    };
+    [ProtectionEventType.CONTENT_RESTORED]: {
+        strategyName: string;
+        targetElement?: HTMLElement | null;
+    };
+    [ProtectionEventType.OVERLAY_SHOWN]: {
+        strategyName: string;
+        overlayType: string;
+        options: OverlayOptions;
+        priority: number;
+        duration?: number;
+    };
+    [ProtectionEventType.OVERLAY_REMOVED]: {
+        strategyName: string;
+        overlayType: string;
+        reason?: string;
+    };
+    [ProtectionEventType.OVERLAY_RESTORED]: {
+        strategyName: string;
+        overlayType: string;
+        reason?: string;
+    };
+    [ProtectionEventType.STRATEGY_REMOVED]: {
+        strategyName: string;
+        reason?: string;
+    };
+    [key: string]: Record<string, unknown>;
+}
+/**
+ * Type-safe typed event interface
+ * Use this instead of unsafe `as` assertions
+ */
+export interface TypedProtectionEvent<T extends ProtectionEventType> {
+    type: T;
+    source: string;
+    timestamp: number;
+    data: EventDataMap[T];
+}
+/**
+ * Type guard to check if an event has a specific type
+ * @param event The event to check
+ * @param eventType The expected event type
+ * @returns True if the event matches the type
+ */
+export declare function isEventType<T extends ProtectionEventType>(event: {
+    type: ProtectionEventType;
+    data?: unknown;
+}, eventType: T): event is TypedProtectionEvent<T>;
+/**
+ * Get typed event data with type safety
+ * Returns undefined if the event type doesn't match
+ * @param event The protection event
+ * @param eventType The expected event type
+ * @returns The typed data or undefined
+ */
+export declare function getTypedEventData<T extends ProtectionEventType>(event: {
+    type: ProtectionEventType;
+    data?: unknown;
+}, eventType: T): EventDataMap[T] | undefined;

package/dist/core/mediator/eventDataTypes.js

@@ -0,0 +1,23 @@
+import { ProtectionEventType } from "./protection-event";
+/**
+ * Type guard to check if an event has a specific type
+ * @param event The event to check
+ * @param eventType The expected event type
+ * @returns True if the event matches the type
+ */
+export function isEventType(event, eventType) {
+    return event.type === eventType;
+}
+/**
+ * Get typed event data with type safety
+ * Returns undefined if the event type doesn't match
+ * @param event The protection event
+ * @param eventType The expected event type
+ * @returns The typed data or undefined
+ */
+export function getTypedEventData(event, eventType) {
+    if (event.type === eventType) {
+        return event.data;
+    }
+    return undefined;
+}

package/dist/core/mediator/handlers/abstractEventHandler.d.ts

@@ -0,0 +1,41 @@
+import type { ProtectionMediator } from "../types";
+import type { ProtectionEvent, ProtectionEventType } from "../protection-event";
+import { LoggableComponent } from "../../../utils/base/LoggableComponent";
+/**
+ * Abstract base class for all event handlers
+ */
+export declare abstract class AbstractEventHandler extends LoggableComponent {
+    protected mediator: ProtectionMediator;
+    protected subscriptionIds: string[];
+    /**
+     * Create a new event handler
+     * @param mediator The protection mediator
+     * @param componentName The name of the component
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(mediator: ProtectionMediator, componentName: string, debugMode?: boolean);
+    /**
+     * Initialize the handler and subscribe to events
+     * This method should be implemented by subclasses
+     */
+    protected abstract initialize(): void;
+    /**
+     * Subscribe to an event and track the subscription ID
+     * @param eventType The event type to subscribe to
+     * @param handler The event handler function
+     * @param options Optional subscription options
+     * @returns The subscription ID
+     */
+    protected subscribe(eventType: ProtectionEventType, handler: (event: ProtectionEvent) => void, options?: {
+        context?: string;
+    }): string;
+    /**
+     * Unsubscribe from all events and clean up
+     */
+    dispose(): void;
+    /**
+     * Additional cleanup to be performed on disposal
+     * This method can be overridden by subclasses
+     */
+    protected onDispose(): void;
+}

package/dist/core/mediator/handlers/abstractEventHandler.js

@@ -0,0 +1,59 @@
+import { LoggableComponent } from "../../../utils/base/LoggableComponent";
+/**
+ * Abstract base class for all event handlers
+ */
+export class AbstractEventHandler extends LoggableComponent {
+    /**
+     * Create a new event handler
+     * @param mediator The protection mediator
+     * @param componentName The name of the component
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(mediator, componentName, debugMode = false) {
+        super(componentName, debugMode);
+        this.subscriptionIds = [];
+        this.mediator = mediator;
+        this.initialize();
+        // `log` is debug-gated by the logger; the outer check is unnecessary.
+        this.log("Initialized and subscribed to events");
+    }
+    /**
+     * Subscribe to an event and track the subscription ID
+     * @param eventType The event type to subscribe to
+     * @param handler The event handler function
+     * @param options Optional subscription options
+     * @returns The subscription ID
+     */
+    subscribe(eventType, handler, options) {
+        const subId = this.mediator.subscribe(eventType, handler, {
+            ...options,
+            context: options?.context || this.COMPONENT_NAME,
+        });
+        this.subscriptionIds.push(subId);
+        if (this.debugMode) {
+            this.log(`Subscribed to ${eventType} with ID ${subId}`);
+        }
+        return subId;
+    }
+    /**
+     * Unsubscribe from all events and clean up
+     */
+    dispose() {
+        if (this.debugMode) {
+            this.log(`Disposing handler, unsubscribing from ${this.subscriptionIds.length} events`);
+        }
+        // Unsubscribe from all events
+        for (const id of this.subscriptionIds) {
+            this.mediator.unsubscribe(id);
+        }
+        this.subscriptionIds = [];
+        this.onDispose();
+    }
+    /**
+     * Additional cleanup to be performed on disposal
+     * This method can be overridden by subclasses
+     */
+    onDispose() {
+        // Default implementation does nothing
+    }
+}

package/dist/core/mediator/handlers/devToolsEventHandler.d.ts

@@ -0,0 +1,9 @@
+import type { ProtectionMediator } from "../types";
+import { AbstractEventHandler } from "./abstractEventHandler";
+export declare class DevToolsEventHandler extends AbstractEventHandler {
+    constructor(mediator: ProtectionMediator, debugMode?: boolean);
+    protected initialize(): void;
+    private handleDevToolsStateChange;
+    private handleDevToolsOpened;
+    private handleDevToolsClosed;
+}

package/dist/core/mediator/handlers/devToolsEventHandler.js

@@ -0,0 +1,95 @@
+import { ProtectionEventType } from "../protection-event";
+import { isEventType } from "../eventDataTypes";
+import { AbstractEventHandler } from "./abstractEventHandler";
+export class DevToolsEventHandler extends AbstractEventHandler {
+    constructor(mediator, debugMode = false) {
+        super(mediator, "DevToolsEventHandler", debugMode);
+    }
+    initialize() {
+        this.subscribe(ProtectionEventType.DEVTOOLS_STATE_CHANGE, this.handleDevToolsStateChange.bind(this));
+    }
+    handleDevToolsStateChange(event) {
+        // Use type guard for type-safe access
+        if (!isEventType(event, ProtectionEventType.DEVTOOLS_STATE_CHANGE)) {
+            this.error("Received invalid event type");
+            return;
+        }
+        this.log(`Handling DevTools state change, isOpen=${event.data.isOpen}`);
+        if (event.data.isOpen) {
+            this.handleDevToolsOpened(event);
+        }
+        else {
+            this.handleDevToolsClosed(event);
+        }
+    }
+    handleDevToolsOpened(event) {
+        const { data } = event;
+        // Show overlay if showOverlay is enabled (defaults to true)
+        if (data.showOverlay !== false) {
+            this.mediator.publish({
+                type: ProtectionEventType.OVERLAY_SHOWN,
+                source: this.COMPONENT_NAME,
+                timestamp: Date.now(),
+                data: {
+                    strategyName: this.COMPONENT_NAME,
+                    overlayType: "devtools",
+                    options: {
+                        ...data.overlayOptions,
+                        blockEvents: true,
+                        autoRestore: true,
+                    },
+                    priority: 10,
+                },
+            });
+        }
+        // Only hide content if hideContent option is explicitly enabled
+        if (data.hideContent === true) {
+            this.mediator.publish({
+                type: ProtectionEventType.CONTENT_HIDDEN,
+                source: this.COMPONENT_NAME,
+                timestamp: Date.now(),
+                data: {
+                    strategyName: this.COMPONENT_NAME,
+                    reason: "devtools_opened",
+                    options: {
+                        title: data.overlayOptions?.title,
+                        message: data.overlayOptions?.message,
+                        secondaryMessage: data.overlayOptions?.secondaryMessage,
+                        textColor: 'black',
+                        backgroundColor: data.overlayOptions?.backgroundColor,
+                    },
+                    targetElement: data.target,
+                    priority: 10,
+                },
+            });
+        }
+    }
+    handleDevToolsClosed(event) {
+        const { data } = event;
+        // Remove overlay if showOverlay was enabled
+        if (data.showOverlay !== false) {
+            this.mediator.publish({
+                type: ProtectionEventType.OVERLAY_REMOVED,
+                source: this.COMPONENT_NAME,
+                timestamp: Date.now(),
+                data: {
+                    strategyName: this.COMPONENT_NAME,
+                    overlayType: "devtools",
+                    reason: "devtools_closed",
+                },
+            });
+        }
+        // Only restore content if hideContent was explicitly enabled
+        if (data.hideContent === true) {
+            this.mediator.publish({
+                type: ProtectionEventType.CONTENT_RESTORED,
+                source: this.COMPONENT_NAME,
+                timestamp: Date.now(),
+                data: {
+                    strategyName: this.COMPONENT_NAME,
+                    targetElement: data.target,
+                },
+            });
+        }
+    }
+}

package/dist/core/mediator/handlers/eventHandlerRegistry.d.ts

@@ -0,0 +1,9 @@
+import type { ProtectionMediator } from "../types";
+export declare class HandlerRegistry {
+    private handlers;
+    private mediator;
+    private debugMode;
+    constructor(mediator: ProtectionMediator, debugMode?: boolean);
+    private initializeHandlers;
+    setDebugMode(enabled: boolean): void;
+}

package/dist/core/mediator/handlers/eventHandlerRegistry.js

@@ -0,0 +1,34 @@
+import { DevToolsEventHandler } from "./devToolsEventHandler";
+import { BrowserExtensionEventHandler } from "./extensionEventHandlers";
+import { FrameEmbeddingEventHandler } from "./iFrameEventHandlers";
+import { ScreenshotEventHandler } from "./screenShotEventHandlers";
+export class HandlerRegistry {
+    constructor(mediator, debugMode = false) {
+        this.handlers = {};
+        this.mediator = mediator;
+        this.debugMode = debugMode;
+        this.initializeHandlers();
+    }
+    initializeHandlers() {
+        // Initialize all handlers
+        this.handlers.devTools = new DevToolsEventHandler(this.mediator, this.debugMode);
+        this.handlers.extension = new BrowserExtensionEventHandler(this.mediator, this.debugMode);
+        this.handlers.screenshot = new ScreenshotEventHandler(this.mediator, this.debugMode);
+        this.handlers.iFrame = new FrameEmbeddingEventHandler(this.mediator, this.debugMode);
+        // Add more handlers as you implement them
+        // this.handlers.screenshot = new ScreenshotEventHandler(this.mediator, this.debugMode);
+        // this.handlers.frameEmbedding = new FrameEmbeddingEventHandler(this.mediator, this.debugMode);
+        if (this.debugMode) {
+            console.log("HandlerRegistry: Initialized all event handlers");
+        }
+    }
+    setDebugMode(enabled) {
+        this.debugMode = enabled;
+        // Update debug mode for all handlers
+        Object.values(this.handlers).forEach(handler => {
+            if (typeof handler.setDebugMode === 'function') {
+                handler.setDebugMode(enabled);
+            }
+        });
+    }
+}

package/dist/core/mediator/handlers/extensionEventHandlers.d.ts

@@ -0,0 +1,40 @@
+import type { ProtectionMediator } from "../types";
+import { ProtectionEvent, ProtectionEventType } from "../protection-event";
+import { TypedProtectionEvent } from "../eventDataTypes";
+import { AbstractEventHandler } from "./abstractEventHandler";
+type ExtensionDetectedEvent = TypedProtectionEvent<typeof ProtectionEventType.EXTENSION_DETECTED>;
+/**
+ * Handler for browser extension detection events
+ */
+export declare class BrowserExtensionEventHandler extends AbstractEventHandler {
+    /**
+     * Create a new BrowserExtensionEventHandler
+     * @param mediator The protection mediator
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(mediator: ProtectionMediator, debugMode?: boolean);
+    /**
+     * Initialize the handler and subscribe to events
+     */
+    protected initialize(): void;
+    /**
+     * Handle extension detection
+     * @param event the ProtectionEvent
+     */
+    handleExtensionDetected(event: ProtectionEvent): void;
+    /**
+     * Handle extension detection
+     * @param event the typed ExtensionDetectedEvent
+     */
+    applyExtensionProtection(event: ExtensionDetectedEvent): void;
+    /**
+     * Remove extension protection
+     * @param event The typed ExtensionDetectedEvent
+     */
+    removeExtensionProtection(event: ExtensionDetectedEvent): void;
+    /**
+     * Additional cleanup to be performed on disposal
+     */
+    protected onDispose(): void;
+}
+export {};