@tindalabs/shield 0.1.0

package/dist/utils/eventManager.js

@@ -0,0 +1,548 @@
+import { isBrowser } from "./environment";
+import { LoggableComponent } from "./base/LoggableComponent";
+/**
+ * EventManager centralizes event handling across protection strategies
+ * It provides a unified API for registering and removing event listeners
+ * and ensures proper cleanup when strategies are removed
+ */
+export class EventManager extends LoggableComponent {
+    /**
+     * Create a new EventManager
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(debugMode = false) {
+        super("EventManager", debugMode);
+        // Main storage: Map<TargetId, Map<EventId, StoredEvent>>
+        this.events = new Map();
+        // WeakMap to associate DOM elements with their target IDs
+        this.targetMap = new WeakMap();
+        // Special symbols for document and window
+        this.DOCUMENT_SYMBOL = Symbol("document");
+        this.WINDOW_SYMBOL = Symbol("window");
+        this.logger.log("Initialized");
+    }
+    /**
+     * Get the EventManager instance (singleton)
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    static getInstance(debugMode = false) {
+        if (!EventManager.instance) {
+            EventManager.instance = new EventManager(debugMode);
+        }
+        // Update debug mode if it's explicitly passed
+        if (arguments.length > 0) {
+            EventManager.instance.setDebugMode(debugMode);
+        }
+        return EventManager.instance;
+    }
+    /**
+     * Register an event listener
+     * @param target The target element, document, or window
+     * @param eventType The type of event (e.g., "click", "keydown")
+     * @param handler The event handler function
+     * @param owner The component or strategy that owns this event
+     * @param options Additional options for the event listener
+     * @returns The ID of the registered event
+     */
+    addEventListener(target, eventType, handler, owner, options) {
+        if (!isBrowser() || !target) {
+            this.logger.log(`Cannot add event, ${!isBrowser() ? "not in browser" : "target is null"}`);
+            return "";
+        }
+        // Get or create target ID
+        const targetId = this.getTargetId(target);
+        if (!targetId)
+            return "";
+        // Get or create event map for this target
+        if (!this.events.has(targetId)) {
+            this.events.set(targetId, new Map());
+        }
+        const targetEvents = this.events.get(targetId);
+        // Generate event ID if not provided
+        const eventId = options?.id || `${owner}-${eventType}-${Date.now()}`;
+        // Set default priority if not specified
+        const priority = options?.priority !== undefined ? options.priority : 0;
+        // Create a wrapped handler with error handling
+        const wrappedHandler = (e) => {
+            try {
+                return handler(e);
+            }
+            catch (error) {
+                this.logger.error(`Error in ${eventType} event handler for ${owner}:`, error);
+                // Continue event propagation by not returning false
+            }
+        };
+        // Store event information
+        const storedEvent = {
+            eventType,
+            handler,
+            wrappedHandler,
+            options,
+            owner,
+            priority,
+        };
+        // Add event listener to the target
+        try {
+            target.addEventListener(eventType, wrappedHandler, options);
+            // Store the event information
+            targetEvents.set(eventId, storedEvent);
+            this.logger.log(`Added ${eventType} event for ${owner} with ID ${eventId} and priority ${priority}`);
+            return eventId;
+        }
+        catch (error) {
+            this.logger.error(`Error adding ${eventType} event:`, error);
+            return "";
+        }
+    }
+    /**
+     * Remove a specific event listener by ID
+     * @param target The target element, document, or window
+     * @param eventId The ID of the event to remove
+     * @returns True if the event was removed, false otherwise
+     */
+    removeEventListener(target, eventId) {
+        if (!isBrowser() || !target) {
+            return false;
+        }
+        const targetId = this.getTargetId(target, false);
+        if (!targetId)
+            return false;
+        const targetEvents = this.events.get(targetId);
+        if (!targetEvents || !targetEvents.has(eventId)) {
+            return false;
+        }
+        // Get the stored event information
+        const storedEvent = targetEvents.get(eventId);
+        // Remove the event listener
+        try {
+            target.removeEventListener(storedEvent.eventType, storedEvent.wrappedHandler, storedEvent.options);
+            // Remove from our map
+            targetEvents.delete(eventId);
+            // Clean up the target map if no more events
+            if (targetEvents.size === 0) {
+                this.events.delete(targetId);
+                // Only remove from targetMap if it's not document or window
+                if (targetId !== this.DOCUMENT_SYMBOL && targetId !== this.WINDOW_SYMBOL) {
+                    this.targetMap.delete(target);
+                }
+            }
+            this.logger.log(`Removed event ${eventId} (${storedEvent.eventType}) for ${storedEvent.owner}`);
+            return true;
+        }
+        catch (error) {
+            this.logger.error(`Error removing event ${eventId}:`, error);
+            return false;
+        }
+    }
+    /**
+     * Remove all event listeners for a specific owner (strategy/component)
+     * @param owner The owner to remove events for
+     * @returns The number of events removed
+     */
+    removeEventsByOwner(owner) {
+        if (!isBrowser())
+            return 0;
+        let removedCount = 0;
+        // We need to track which target IDs to clean up after removal
+        const emptyTargetIds = [];
+        // Iterate through all targets
+        for (const [targetId, targetEvents] of this.events.entries()) {
+            // Find all events owned by this owner
+            const eventsToRemove = [];
+            for (const [eventId, storedEvent] of targetEvents.entries()) {
+                if (storedEvent.owner === owner) {
+                    eventsToRemove.push(eventId);
+                }
+            }
+            // If we have events to remove, try to get the target
+            if (eventsToRemove.length > 0) {
+                const target = this.getTargetFromId(targetId);
+                if (target) {
+                    // For document and window targets, we can reliably remove events
+                    if (targetId === this.DOCUMENT_SYMBOL || targetId === this.WINDOW_SYMBOL) {
+                        // Remove each event
+                        for (const eventId of eventsToRemove) {
+                            if (this.removeEventListener(target, eventId)) {
+                                removedCount++;
+                            }
+                        }
+                    }
+                    else {
+                        // For DOM elements that might be recreated (like in Vue),
+                        // we need to be more cautious and remove handlers directly
+                        for (const eventId of eventsToRemove) {
+                            const storedEvent = targetEvents.get(eventId);
+                            if (storedEvent) {
+                                try {
+                                    target.removeEventListener(storedEvent.eventType, storedEvent.wrappedHandler, storedEvent.options);
+                                    targetEvents.delete(eventId);
+                                    removedCount++;
+                                    this.logger.log(`Removed event ${eventId} (${storedEvent.eventType}) for ${storedEvent.owner}`);
+                                }
+                                catch (e) {
+                                    // If we can't remove the listener, just remove from our maps
+                                    targetEvents.delete(eventId);
+                                    removedCount++;
+                                    this.logger.log(`Removed event ${eventId} from maps only - could not remove listener directly (${String(e)})`);
+                                }
+                            }
+                        }
+                    }
+                }
+                else {
+                    // For targets we can't retrieve (due to WeakMap limitations),
+                    // we'll just remove the event entries from our maps
+                    for (const eventId of eventsToRemove) {
+                        const storedEvent = targetEvents.get(eventId);
+                        if (storedEvent) {
+                            targetEvents.delete(eventId);
+                            removedCount++;
+                            this.logger.log(`Removed event ${eventId} (${storedEvent.eventType}) for ${storedEvent.owner} (target unavailable)`);
+                        }
+                    }
+                }
+                // Check if the target events map is now empty
+                if (targetEvents.size === 0) {
+                    emptyTargetIds.push(targetId);
+                }
+            }
+        }
+        // Clean up empty target maps
+        for (const targetId of emptyTargetIds) {
+            this.events.delete(targetId);
+        }
+        if (removedCount > 0) {
+            this.logger.log(`Removed ${removedCount} events for owner ${owner}`);
+        }
+        return removedCount;
+    }
+    /**
+     * Remove all event listeners for a specific target
+     * @param target The target to remove events from
+     * @returns The number of events removed
+     */
+    removeAllEventsForTarget(target) {
+        if (!isBrowser() || !target)
+            return 0;
+        const targetId = this.getTargetId(target, false);
+        if (!targetId)
+            return 0;
+        const targetEvents = this.events.get(targetId);
+        if (!targetEvents)
+            return 0;
+        let removedCount = 0;
+        // Create a copy of the event IDs to avoid modification during iteration
+        const eventIds = Array.from(targetEvents.keys());
+        for (const eventId of eventIds) {
+            try {
+                const storedEvent = targetEvents.get(eventId);
+                if (storedEvent) {
+                    // Try to properly remove the event listener
+                    target.removeEventListener(storedEvent.eventType, storedEvent.wrappedHandler, storedEvent.options);
+                    // Remove from our map
+                    targetEvents.delete(eventId);
+                    removedCount++;
+                    this.logger.log(`Removed event ${eventId} (${storedEvent.eventType}) from target`);
+                }
+            }
+            catch (e) {
+                // If removal fails, still remove from our maps
+                targetEvents.delete(eventId);
+                removedCount++;
+                this.logger.log(`Removed event ${eventId} from maps (${String(e)})`);
+            }
+        }
+        if (removedCount > 0) {
+            this.logger.log(`Removed ${removedCount} events for target`);
+        }
+        return removedCount;
+    }
+    /**
+     * Get all event IDs for a specific owner
+     * @param owner The owner to get events for
+     * @returns Array of event IDs
+     */
+    getEventsByOwner(owner) {
+        if (!isBrowser())
+            return [];
+        const eventIds = [];
+        for (const targetEvents of this.events.values()) {
+            for (const [eventId, storedEvent] of targetEvents.entries()) {
+                if (storedEvent.owner === owner) {
+                    eventIds.push(eventId);
+                }
+            }
+        }
+        return eventIds;
+    }
+    /**
+     * Check if an event exists
+     * @param target The target element
+     * @param eventId The event ID
+     * @returns True if the event exists
+     */
+    hasEvent(target, eventId) {
+        if (!isBrowser() || !target)
+            return false;
+        const targetId = this.getTargetId(target, false);
+        if (!targetId)
+            return false;
+        const targetEvents = this.events.get(targetId);
+        return targetEvents ? targetEvents.has(eventId) : false;
+    }
+    /**
+     * Get a unique identifier for a target
+     * @param target The target element, document, or window
+     * @param create Whether to create a new ID if one doesn't exist
+     * @returns The target ID
+     */
+    getTargetId(target, create = true) {
+        // Special cases for document and window
+        if (target === document) {
+            return this.DOCUMENT_SYMBOL;
+        }
+        if (target === window) {
+            return this.WINDOW_SYMBOL;
+        }
+        // Check if we already have an ID for this target
+        let targetId = this.targetMap.get(target);
+        // Create a new ID if needed
+        if (!targetId && create) {
+            targetId = `target-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+            this.targetMap.set(target, targetId);
+        }
+        return targetId || null;
+    }
+    /**
+     * Get a target from its ID
+     * @param targetId The target ID
+     * @returns The target element or null
+     */
+    getTargetFromId(targetId) {
+        if (!isBrowser())
+            return null;
+        // Special cases for document and window
+        if (targetId === this.DOCUMENT_SYMBOL) {
+            return document;
+        }
+        if (targetId === this.WINDOW_SYMBOL) {
+            return window;
+        }
+        // For other targets, we can't easily look up by ID since WeakMap doesn't support iteration
+        // This is a limitation of WeakMap, but in practice, most events will be on document/window
+        // For element-specific events, we'll need to rely on the caller having a reference to the element
+        // Return null for other target IDs - this means some operations like removeEventsByOwner
+        // will only work fully for document and window events
+        this.logger.warn(`Cannot retrieve target for ID ${String(targetId)}. This is a limitation for element-specific events.`);
+        return null;
+    }
+    /**
+     * Get the number of registered events
+     * @returns The total number of registered events
+     */
+    getEventCount() {
+        let count = 0;
+        for (const targetEvents of this.events.values()) {
+            count += targetEvents.size;
+        }
+        return count;
+    }
+    /**
+     * Get debug information about registered events
+     * @returns Object with debug information
+     */
+    getDebugInfo() {
+        const eventsByOwner = {};
+        const eventsByType = {};
+        let totalEvents = 0;
+        const eventDetails = [];
+        for (const [targetId, targetEvents] of this.events.entries()) {
+            for (const [eventId, storedEvent] of targetEvents.entries()) {
+                totalEvents++;
+                // Count by owner
+                eventsByOwner[storedEvent.owner] = (eventsByOwner[storedEvent.owner] || 0) + 1;
+                // Count by event type
+                eventsByType[storedEvent.eventType] = (eventsByType[storedEvent.eventType] || 0) + 1;
+                // Add detailed event info
+                eventDetails.push({
+                    targetId: targetId,
+                    eventId,
+                    eventType: storedEvent.eventType,
+                    owner: storedEvent.owner,
+                    priority: storedEvent.priority,
+                });
+            }
+        }
+        return {
+            totalEvents,
+            eventsByOwner,
+            eventsByType,
+            eventDetails,
+        };
+    }
+    /**
+     * Clear all registered events
+     * @returns The number of events removed
+     */
+    clearAllEvents() {
+        if (!isBrowser())
+            return 0;
+        let removedCount = 0;
+        // Handle document and window events first
+        if (this.events.has(this.DOCUMENT_SYMBOL)) {
+            removedCount += this.removeAllEventsForTarget(document);
+        }
+        if (this.events.has(this.WINDOW_SYMBOL)) {
+            removedCount += this.removeAllEventsForTarget(window);
+        }
+        // For other targets, we'll have to just clear our maps
+        // Create a copy of the entries to avoid modification during iteration
+        const entries = Array.from(this.events.entries());
+        for (const [targetId, targetEvents] of entries) {
+            // Skip document and window as we already handled them
+            if (targetId === this.DOCUMENT_SYMBOL || targetId === this.WINDOW_SYMBOL) {
+                continue;
+            }
+            // For other targets, just clear the events from our maps
+            removedCount += targetEvents.size;
+            this.events.delete(targetId);
+            this.logger.log(`Cleared ${targetEvents.size} events for target ID ${String(targetId)} (target unavailable)`);
+        }
+        // Clear the target map
+        this.targetMap = new WeakMap();
+        if (removedCount > 0) {
+            this.logger.log(`Cleared all ${removedCount} events`);
+        }
+        return removedCount;
+    }
+    /**
+     * Check if an event handler is already registered for this target, event type, and owner
+     * This helps prevent duplicate registrations
+     * @param target The target element
+     * @param eventType The event type (e.g., "click", "contextmenu")
+     * @param owner The owner of the event handler
+     * @returns True if an event handler is already registered
+     */
+    hasRegisteredEventType(target, eventType, owner) {
+        if (!isBrowser() || !target)
+            return false;
+        const targetId = this.getTargetId(target, false);
+        if (!targetId)
+            return false;
+        const targetEvents = this.events.get(targetId);
+        if (!targetEvents)
+            return false;
+        // Check if any event of this type is already registered for this owner
+        for (const storedEvent of targetEvents.values()) {
+            if (storedEvent.eventType === eventType && storedEvent.owner === owner) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Check for potential conflicts with existing event listeners
+     * @param target The target element
+     * @param eventType The event type (e.g., "click", "contextmenu")
+     * @param owner The owner of the event handler
+     * @returns Object with conflict information
+     */
+    checkForConflicts(target, eventType, owner) {
+        const result = {
+            hasConflicts: false,
+            conflictsWith: [],
+        };
+        if (!isBrowser() || !target) {
+            return result;
+        }
+        const targetId = this.getTargetId(target, false);
+        if (!targetId)
+            return result;
+        const targetEvents = this.events.get(targetId);
+        if (!targetEvents)
+            return result;
+        for (const [eventId, storedEvent] of targetEvents.entries()) {
+            if (storedEvent.eventType === eventType && storedEvent.owner !== owner) {
+                result.hasConflicts = true;
+                result.conflictsWith.push({
+                    owner: storedEvent.owner,
+                    eventId,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Get events of a specific type for a target
+     * @param target The target element
+     * @param eventType The event type (e.g., "click", "contextmenu")
+     * @returns Array of event information
+     */
+    getEventsByType(target, eventType) {
+        const events = [];
+        if (!isBrowser() || !target) {
+            return events;
+        }
+        const targetId = this.getTargetId(target, false);
+        if (!targetId)
+            return events;
+        const targetEvents = this.events.get(targetId);
+        if (!targetEvents)
+            return events;
+        for (const [eventId, storedEvent] of targetEvents.entries()) {
+            if (storedEvent.eventType === eventType) {
+                events.push({
+                    eventId,
+                    owner: storedEvent.owner,
+                    priority: storedEvent.priority,
+                });
+            }
+        }
+        // Sort by priority (higher first)
+        return events.sort((a, b) => b.priority - a.priority);
+    }
+    /**
+     * Remove event listeners by selector
+     * Useful for Vue components and other dynamically created elements
+     * @param selector CSS selector to match elements
+     * @param eventType The event type (e.g., "click", "contextmenu")
+     * @param owner The owner of the event handler
+     * @returns The number of events removed
+     */
+    removeEventsBySelector(selector, eventType, owner) {
+        if (!isBrowser())
+            return 0;
+        let removedCount = 0;
+        try {
+            // Find all matching elements
+            const elements = document.querySelectorAll(selector);
+            if (elements.length > 0) {
+                this.logger.log(`Attempting to remove ${eventType} events for ${owner} on ${elements.length} matched elements`);
+                // For each element, find and remove matching events
+                elements.forEach((element) => {
+                    const targetId = this.getTargetId(element, false);
+                    if (targetId) {
+                        const targetEvents = this.events.get(targetId);
+                        if (targetEvents) {
+                            for (const [eventId, storedEvent] of targetEvents.entries()) {
+                                if (storedEvent.owner === owner && storedEvent.eventType === eventType) {
+                                    element.removeEventListener(eventType, storedEvent.wrappedHandler, storedEvent.options);
+                                    targetEvents.delete(eventId);
+                                    removedCount++;
+                                    this.logger.log(`Removed ${eventType} event for ${owner} via selector`);
+                                }
+                            }
+                        }
+                    }
+                });
+            }
+        }
+        catch (error) {
+            this.logger.error("Error removing events by selector:", error);
+        }
+        return removedCount;
+    }
+}
+EventManager.instance = null;
+// Export a singleton instance
+export const eventManager = EventManager.getInstance();

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './environment';
+export * from './dom';

package/dist/utils/index.js

@@ -0,0 +1,3 @@
+// BARREL FILE
+export * from './environment';
+export * from './dom';

package/dist/utils/intervalManager.d.ts

@@ -0,0 +1,91 @@
+import { LoggableComponent } from "./base/LoggableComponent";
+export type IntervalTask = {
+    id: string;
+    callback: () => void;
+    frequency: number;
+    lastRun?: number;
+    isActive: boolean;
+};
+/**
+ * Manages periodic tasks for the content protection toolkit
+ * Consolidates multiple interval timers into a single efficient timer
+ */
+export declare class IntervalManager extends LoggableComponent {
+    private tasks;
+    private intervalId;
+    private intervalFrequency;
+    private isRunning;
+    /**
+     * Create a new IntervalManager
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(debugMode?: boolean);
+    /**
+     * Register a new task to be executed periodically
+     * @param id Unique identifier for the task
+     * @param callback Function to execute
+     * @param frequency How often to run the task in milliseconds
+     * @returns The task ID for later reference
+     */
+    registerTask(id: string, callback: () => void, frequency: number): string;
+    /**
+     * Unregister a task by ID
+     * @param id Task ID to remove
+     * @returns True if the task was found and removed
+     */
+    unregisterTask(id: string): boolean;
+    /**
+     * Pause a specific task without removing it
+     * @param id Task ID to pause
+     * @returns True if the task was found and paused
+     */
+    pauseTask(id: string): boolean;
+    /**
+     * Resume a paused task
+     * @param id Task ID to resume
+     * @returns True if the task was found and resumed
+     */
+    resumeTask(id: string): boolean;
+    /**
+     * Start the interval timer
+     */
+    private startInterval;
+    /**
+     * Stop the interval timer
+     */
+    private stopInterval;
+    /**
+     * Execute all tasks that are due to run
+     */
+    private executeEligibleTasks;
+    /**
+     * Force execution of a specific task immediately
+     * @param id Task ID to execute
+     * @returns True if the task was found and executed
+     */
+    executeTaskNow(id: string): boolean;
+    /**
+     * Get the current status of all registered tasks
+     * @returns Array of task status objects
+     */
+    getTasksStatus(): Array<{
+        id: string;
+        isActive: boolean;
+        frequency: number;
+        lastRun: number | undefined;
+        timeSinceLastRun: number | null;
+    }>;
+    /**
+     * Clean up and stop all intervals
+     */
+    dispose(): void;
+    /**
+     * Update the base interval frequency
+     * @param frequency New frequency in milliseconds
+     */
+    setIntervalFrequency(frequency: number): void;
+}
+/**
+ * Create a singleton instance for use throughout the application
+ */
+export declare const intervalManager: IntervalManager;