content-security-toolkit 1.0.0

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

@@ -0,0 +1,86 @@
+import { ProtectionEvent, ProtectionEventType } from './protection-event';
+import { ProtectionEventHandler, ProtectionMediator, Subscription, SubscriptionOptions } from './types';
+/**
+ * Mediator for coordinating communication between protection strategies
+ * Implements the mediator pattern to decouple strategies and enable event-based communication
+ */
+export declare class ContentProtectionMediator implements ProtectionMediator {
+    private subscriptions;
+    private subscriptionCounter;
+    private debugMode;
+    private eventHistory;
+    private readonly MAX_HISTORY_SIZE;
+    /**
+     * Create a new ContentProtectionMediator
+     * @param debugMode Enable debug mode for detailed logging
+     */
+    constructor(debugMode?: boolean);
+    /**
+     * 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: ProtectionEventType, handler: ProtectionEventHandler, options?: SubscriptionOptions): string;
+    /**
+     * Unsubscribe from an event
+     * @param subscriptionId ID of the subscription to remove
+     * @returns True if the subscription was found and removed
+     */
+    unsubscribe(subscriptionId: string): boolean;
+    /**
+     * Unsubscribe all handlers with a specific context
+     * @param context Context to unsubscribe (e.g., strategy name)
+     * @returns Number of subscriptions removed
+     */
+    unsubscribeByContext(context: string): number;
+    /**
+     * Publish an event to all subscribers
+     * @param event Event to publish
+     */
+    publish(event: ProtectionEvent): void;
+    /**
+     * Get all subscriptions for a specific event type
+     * @param eventType Type of event to get subscriptions for
+     * @returns Array of subscriptions
+     */
+    getSubscriptions(eventType: ProtectionEventType): Subscription[];
+    /**
+     * Get all subscriptions
+     * @returns Map of event types to subscriptions
+     */
+    getAllSubscriptions(): Map<ProtectionEventType, Subscription[]>;
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Get debug information about the mediator
+     * @returns Object with debug information
+     */
+    getDebugInfo(): {
+        subscriptionCount: number;
+        eventTypeCount: number;
+        eventTypes: string[];
+        recentEvents: ProtectionEvent[];
+    };
+    /**
+     * Add an event to the history
+     * @param event Event to add
+     */
+    private addToEventHistory;
+    /**
+     * Clear all subscriptions
+     * @returns Number of subscriptions cleared
+     */
+    clearAllSubscriptions(): number;
+    /**
+     * Helper method to create and publish an event
+     * @param type Event type
+     * @param source Source of the event
+     * @param data Additional data
+     */
+    createAndPublishEvent(type: ProtectionEventType, source: string, data?: unknown): void;
+}

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,205 @@
+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
+ */
+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.MEDIATOR_INITIALIZED]: {
+        strategies: string[];
+    };
+    [ProtectionEventType.MEDIATOR_DISPOSED]: {
+        reason?: string;
+    };
+    [ProtectionEventType.KEYBOARD_SHORTCUTS_REQUESTED]: {
+        requestingStrategy: string;
+        categories?: string[];
+    };
+    [ProtectionEventType.KEYBOARD_SHORTCUTS_PROVIDED]: {
+        providingStrategy: string;
+        shortcuts: Array<{
+            id: string;
+            keys: string[];
+            description: string;
+            category: string;
+        }>;
+    };
+    [ProtectionEventType.KEYBOARD_SHORTCUTS_UPDATED]: {
+        updatingStrategy: string;
+        addedShortcuts?: Array<{
+            id: string;
+            keys: string[];
+            description: string;
+            category: string;
+        }>;
+        removedShortcutIds?: string[];
+    };
+    [ProtectionEventType.STRATEGY_APPLIED]: {
+        strategyName: string;
+        options?: Record<string, unknown>;
+    };
+    [ProtectionEventType.STRATEGY_REMOVED]: {
+        strategyName: string;
+        reason?: string;
+    };
+    [ProtectionEventType.STRATEGY_UPDATED]: {
+        strategyName: string;
+        changes: Record<string, unknown>;
+    };
+    [ProtectionEventType.CONTEXT_MENU_ATTEMPT]: {
+        target?: HTMLElement | null;
+        prevented: boolean;
+    };
+    [ProtectionEventType.SELECTION_ATTEMPT]: {
+        target?: HTMLElement | null;
+        selectedText?: string;
+        prevented: boolean;
+    };
+    [ProtectionEventType.DRAG_ATTEMPT]: {
+        target?: HTMLElement | null;
+        prevented: boolean;
+    };
+    [ProtectionEventType.KEYBOARD_SHORTCUT_BLOCKED]: {
+        key: string;
+        code: string;
+        ctrlKey: boolean;
+        altKey: boolean;
+        shiftKey: boolean;
+        metaKey: boolean;
+        shortcutId?: string;
+        category?: string;
+    };
+    [ProtectionEventType.PRINT_ATTEMPT]: {
+        prevented: boolean;
+        reason?: string;
+    };
+    [ProtectionEventType.FULLSCREEN_CHANGE]: {
+        isFullscreen: boolean;
+        prevented: boolean;
+        reason?: string;
+    };
+    [ProtectionEventType.WATERMARK_TAMPERED]: {
+        watermarkId: string;
+        tamperedElement?: HTMLElement | null;
+        originalContent?: string;
+    };
+    [ProtectionEventType.OVERLAY_RESTORED]: {
+        strategyName: string;
+        overlayType: string;
+        reason?: string;
+    };
+    [ProtectionEventType.WATERMARK_CREATED]: {
+        watermarkId: string;
+        targetElement?: HTMLElement | null;
+        options?: Record<string, unknown>;
+    };
+    [ProtectionEventType.WATERMARK_REMOVED]: {
+        watermarkId: string;
+        reason?: string;
+    };
+    [ProtectionEventType.ERROR_OCCURRED]: {
+        error: Error | string;
+        source: string;
+        context?: Record<string, unknown>;
+    };
+    [ProtectionEventType.DEBUG_MESSAGE]: {
+        message: string;
+        level: "log" | "warn" | "error" | "info";
+        data?: unknown;
+    };
+    [ProtectionEventType.CONFIG_UPDATED]: {
+        configKey: string;
+        oldValue?: unknown;
+        newValue: unknown;
+    };
+    [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,67 @@
+import type { ProtectionMediator } from "../types";
+import type { ProtectionEvent, ProtectionEventType } from "../protection-event";
+import { SimpleLoggingService } from "../../../utils/logging/simple/SimpleLoggingService";
+/**
+ * Abstract base class for all event handlers
+ */
+export declare abstract class AbstractEventHandler {
+    protected mediator: ProtectionMediator;
+    protected readonly COMPONENT_NAME: string;
+    protected logger: SimpleLoggingService;
+    protected debugMode: boolean;
+    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;
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled: boolean): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}