@tindalabs/shield 0.1.0

package/dist/utils/protectedContentManager.js

@@ -0,0 +1,424 @@
+import { ProtectionEventType } from "../core/mediator/protection-event";
+import { isEventType } from "../core/mediator/eventDataTypes";
+import { LoggableComponent } from "./base/LoggableComponent";
+/**
+ * Utility class to manage protected content by hiding and revealing it
+ */
+export class ProtectedContentManager extends LoggableComponent {
+    /**
+     * Create a new ProtectedContentManager
+     * @param targetElement Element containing sensitive content to protect
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(targetElement, debugMode = false) {
+        super("ProtectedContentManager", debugMode);
+        this.mediator = null;
+        this.originalContent = null;
+        // Track content states by owner
+        this.contentStates = new Map();
+        // Currently active content state
+        this.activeStateId = null;
+        // Queue of content state IDs waiting to be applied
+        this.stateQueue = [];
+        this.lastHideReason = '';
+        this.targetElement = targetElement;
+    }
+    /**
+     * Set the mediator to communicate with the other components
+     * @param mediator The protection mediator instance
+     */
+    setMediator(mediator) {
+        this.mediator = mediator;
+        // Subscribe only to general events directly related to content management
+        this.mediator.subscribe(ProtectionEventType.CONTENT_HIDDEN, this.handleContentHidden.bind(this), {
+            context: this.COMPONENT_NAME,
+        });
+        this.mediator.subscribe(ProtectionEventType.CONTENT_RESTORED, this.handleContentRestored.bind(this), {
+            context: this.COMPONENT_NAME,
+        });
+        this.logger.log("Mediator set and subscriptions established");
+    }
+    /**
+     * Handle content hidden event
+     * @param event The protection event containing content hidden data
+     */
+    handleContentHidden(event) {
+        try {
+            this.logger.log(`Received content hidden event from ${event.source}`, event.data);
+            // Use type guard for type-safe access
+            if (!isEventType(event, ProtectionEventType.CONTENT_HIDDEN)) {
+                this.logger.error("Received invalid event type for CONTENT_HIDDEN");
+                return;
+            }
+            const { data } = event;
+            if (!data || !data.options)
+                return;
+            // Only process if this is for our target element or we're the default handler
+            if (data.targetElement && data.targetElement !== this.targetElement)
+                return;
+            // Register the content state
+            this.registerContentState(data.strategyName, data.reason, data.options, data.priority || 0);
+        }
+        catch (error) {
+            this.logger.error("Error handling content hidden event", error);
+        }
+    }
+    /**
+     * Handle content restored event
+     * @param event The protection event containing content restored data
+     */
+    handleContentRestored(event) {
+        try {
+            this.logger.log(`Received content restored event from ${event.source}`, event.data);
+            // Use type guard for type-safe access
+            if (!isEventType(event, ProtectionEventType.CONTENT_RESTORED)) {
+                this.logger.error("Received invalid event type for CONTENT_RESTORED");
+                return;
+            }
+            const { data } = event;
+            // Only process if this is for our target element or we're the default handler
+            if (data && data.targetElement && data.targetElement !== this.targetElement)
+                return;
+            // Remove content states for this owner
+            this.removeContentStatesByOwner(data.strategyName);
+        }
+        catch (error) {
+            this.logger.error("Error handling content restored event", error);
+        }
+    }
+    /**
+     * Register a new content state
+     * @param owner The strategy or component that owns this state
+     * @param reason The reason for hiding content
+     * @param options Options for the placeholder
+     * @param priority Priority for content hiding (higher numbers take precedence)
+     * @returns The ID of the registered content state
+     */
+    registerContentState(owner, reason, options, priority = 0) {
+        // Generate a unique ID for the content state
+        const stateId = `content-state-${owner}-${reason}-${Date.now()}`;
+        // Create the stored content state object
+        const contentState = {
+            id: stateId,
+            owner,
+            reason,
+            options: { ...options },
+            priority,
+            hiddenAt: Date.now(),
+        };
+        // Store the content state
+        this.contentStates.set(stateId, contentState);
+        this.logger.log(`Registered content state ${stateId} for ${owner} (${reason})`);
+        // If no active state, apply this one immediately
+        if (!this.activeStateId) {
+            this.applyContentStateById(stateId);
+        }
+        else {
+            // Otherwise, add to queue based on priority
+            this.addToQueue(stateId);
+            // Check if this state should replace the current one based on priority
+            const activeState = this.contentStates.get(this.activeStateId);
+            const newState = this.contentStates.get(stateId);
+            if (activeState && newState && newState.priority > activeState.priority) {
+                this.logger.log("New state has higher priority, replacing active state");
+                // Re-queue the displaced active state BEFORE applying the new one,
+                // so it can resurface when the new (higher-priority) state is
+                // dismissed. Without this step the displaced state is orphaned —
+                // it stays in `contentStates` but is neither active nor queued,
+                // so the dismiss path falls back to the original content instead
+                // of returning to the displaced protection. Mirrors the
+                // SecurityOverlayManager re-queue fix in commit 4d14467.
+                this.addToQueue(this.activeStateId);
+                // Apply the new state
+                this.applyContentStateById(stateId);
+            }
+        }
+        return stateId;
+    }
+    /**
+     * Add a content state to the queue
+     * @param stateId ID of the content state to add to queue
+     */
+    addToQueue(stateId) {
+        // Add to queue if not already in it
+        if (!this.stateQueue.includes(stateId)) {
+            this.stateQueue.push(stateId);
+            // Sort queue by priority (highest first)
+            this.stateQueue.sort((a, b) => {
+                const stateA = this.contentStates.get(a);
+                const stateB = this.contentStates.get(b);
+                if (!stateA || !stateB)
+                    return 0;
+                return stateB.priority - stateA.priority;
+            });
+            this.logger.log(`Added state ${stateId} to queue, position ${this.stateQueue.indexOf(stateId) + 1}/${this.stateQueue.length}`);
+        }
+    }
+    /**
+     * Apply a specific content state by ID
+     * @param stateId ID of the content state to apply
+     * @returns True if the state was applied successfully
+     */
+    applyContentStateById(stateId) {
+        const state = this.contentStates.get(stateId);
+        if (!state)
+            return false;
+        this.logger.log(`Applying content state ${stateId} (${state.reason})`);
+        // Track the reason for hiding content (for callback)
+        this.lastHideReason = state.reason;
+        // Hide content with the specified options
+        this.hideContent(state.options);
+        // Set as active state
+        this.activeStateId = stateId;
+        // Remove from queue if it's in there
+        this.stateQueue = this.stateQueue.filter((id) => id !== stateId);
+        return true;
+    }
+    /**
+     * Remove content states for a specific owner
+     * @param owner The owner to remove states for
+     * @returns The number of states removed
+     */
+    removeContentStatesByOwner(owner) {
+        let removedCount = 0;
+        const statesToRemove = [];
+        // Find all states owned by this owner
+        for (const [stateId, state] of this.contentStates.entries()) {
+            if (state.owner === owner) {
+                statesToRemove.push(stateId);
+            }
+        }
+        // Remove each state
+        for (const stateId of statesToRemove) {
+            this.contentStates.delete(stateId);
+            removedCount++;
+            // If this was the active state, we need to restore content or apply the next state
+            if (this.activeStateId === stateId) {
+                this.activeStateId = null;
+                // Check if there are other states in the queue
+                if (this.stateQueue.length > 0) {
+                    // Apply the next state in the queue
+                    const nextStateId = this.stateQueue.shift();
+                    if (nextStateId) {
+                        this.applyContentStateById(nextStateId);
+                    }
+                }
+                else {
+                    // No more states, restore the original content
+                    this.restoreContent();
+                }
+            }
+            else {
+                // If it wasn't active, just remove from queue if present
+                this.stateQueue = this.stateQueue.filter((id) => id !== stateId);
+            }
+        }
+        if (removedCount > 0) {
+            this.logger.log(`Removed ${removedCount} content states for owner ${owner}`);
+        }
+        return removedCount;
+    }
+    /**
+     * Hide the original content and replace it with a placeholder
+     * @param options Options for customizing the placeholder
+     * @returns True if content was hidden, false if there was no content to hide
+     */
+    hideContent(options) {
+        if (!this.targetElement)
+            return false;
+        // Store original content if not already stored
+        if (this.originalContent === null) {
+            this.originalContent = this.targetElement.innerHTML;
+            this.logger.log("Original content stored");
+        }
+        // Create placeholder content with custom styles
+        const placeholderStyles = {
+            padding: "20px",
+            textAlign: "center",
+            color: options.textColor || "white",
+            backgroundColor: options.backgroundColor || "rgba(0, 0, 0, 0.05)",
+            borderRadius: "8px",
+            margin: "20px",
+            boxShadow: "0 2px 10px rgba(0, 0, 0, 0.1)",
+        };
+        // Convert styles object to inline style string
+        const styleString = Object.entries(placeholderStyles)
+            .map(([key, value]) => `${key}: ${value}`)
+            .join("; ");
+        // Replace content with a placeholder that uses the options text
+        this.targetElement.innerHTML = `
+      <div style="${styleString}">
+        <h2 style="font-size: 24px; margin-bottom: 20px; color: ${options.textColor || "black"};">
+          ${options.title || "Content Protected"}
+        </h2>
+        <p style="font-size: 16px; margin-bottom: 15px; color: ${options.textColor || "black"};">
+          ${options.message || "This content is protected for security reasons."}
+        </p>
+        ${options.secondaryMessage
+            ? `
+          <p style="font-size: 16px; color: ${options.textColor || "black"};">
+            ${options.secondaryMessage}
+          </p>
+        `
+            : ""}
+        <div style="margin-top: 20px; padding-top: 20px; border-top: 1px solid rgba(255, 255, 255, 0.2);">
+          <p style="font-size: 14px; color: ${options.textColor || "black"}; opacity: 0.8;">
+            This content is protected by ContentSecurityToolkit
+          </p>
+        </div>
+      </div>
+    `;
+        this.logger.log("Content hidden");
+        // Call the onContentHidden callback if registered
+        if (this.onContentHiddenCallback) {
+            try {
+                this.onContentHiddenCallback(this.lastHideReason || 'unknown', this.targetElement);
+                this.logger.log("onContentHidden callback invoked");
+            }
+            catch (error) {
+                this.logger.error("Error in onContentHidden callback", error);
+            }
+        }
+        return true;
+    }
+    /**
+     * Restore the original content
+     * @returns True if content was restored, false if there was no content to restore
+     */
+    restoreContent() {
+        if (!this.targetElement || this.originalContent === null)
+            return false;
+        // Restore the original content
+        this.targetElement.innerHTML = this.originalContent;
+        this.originalContent = null;
+        this.logger.log("Original content restored");
+        // Call the onContentRestored callback if registered
+        if (this.onContentRestoredCallback) {
+            try {
+                this.onContentRestoredCallback(this.targetElement);
+                this.logger.log("onContentRestored callback invoked");
+            }
+            catch (error) {
+                this.logger.error("Error in onContentRestored callback", error);
+            }
+        }
+        return true;
+    }
+    /**
+     * Check if content is currently hidden
+     * @returns True if content is hidden, false otherwise
+     */
+    isContentHidden() {
+        return this.originalContent !== null;
+    }
+    /**
+     * Get the currently active content state ID
+     * @returns The active content state ID or null if none is active
+     */
+    getActiveContentStateId() {
+        return this.activeStateId;
+    }
+    /**
+     * Get all content states for a specific owner
+     * @param owner The owner to get states for
+     * @returns Array of content state IDs
+     */
+    getContentStatesByOwner(owner) {
+        const stateIds = [];
+        for (const [stateId, state] of this.contentStates.entries()) {
+            if (state.owner === owner) {
+                stateIds.push(stateId);
+            }
+        }
+        return stateIds;
+    }
+    /**
+     * Update the target element
+     * @param element New target element
+     */
+    updateTargetElement(element) {
+        // If content is hidden, restore it before changing the target
+        if (this.isContentHidden()) {
+            this.restoreContent();
+        }
+        this.targetElement = element;
+        // If we had an active state, reapply it to the new target
+        if (this.activeStateId) {
+            const activeState = this.contentStates.get(this.activeStateId);
+            if (activeState) {
+                this.hideContent(activeState.options);
+            }
+        }
+        this.logger.log("Target element updated");
+    }
+    /**
+     * Get the current target element
+     * @returns The current target element
+     */
+    getTargetElement() {
+        return this.targetElement;
+    }
+    /**
+     * Set callbacks for content visibility changes
+     * Useful for frameworks like Vue that need to re-mount components after content restoration
+     * @param onHidden Callback invoked when content is hidden
+     * @param onRestored Callback invoked when content is restored
+     */
+    setContentCallbacks(onHidden, onRestored) {
+        this.onContentHiddenCallback = onHidden;
+        this.onContentRestoredCallback = onRestored;
+        this.logger.log("Content callbacks set");
+    }
+    /**
+     * Clear all content states
+     * @returns The number of states removed
+     */
+    clearAllContentStates() {
+        const stateCount = this.contentStates.size;
+        // Restore content if it's hidden
+        if (this.isContentHidden()) {
+            this.restoreContent();
+        }
+        // Clear all states and queue
+        this.contentStates.clear();
+        this.stateQueue = [];
+        this.activeStateId = null;
+        if (stateCount > 0) {
+            this.logger.log(`Cleared all ${stateCount} content states`);
+        }
+        return stateCount;
+    }
+    /**
+     * Get debug information about content states
+     * @returns Object with debug information
+     */
+    getDebugInfo() {
+        const statesByOwner = {};
+        const statesByReason = {};
+        let totalStates = 0;
+        const stateDetails = [];
+        for (const [stateId, state] of this.contentStates.entries()) {
+            totalStates++;
+            // Count by owner
+            statesByOwner[state.owner] = (statesByOwner[state.owner] || 0) + 1;
+            // Count by reason
+            statesByReason[state.reason] = (statesByReason[state.reason] || 0) + 1;
+            // Add detailed state info
+            stateDetails.push({
+                id: stateId,
+                owner: state.owner,
+                reason: state.reason,
+                priority: state.priority,
+                hiddenAt: state.hiddenAt,
+            });
+        }
+        return {
+            totalStates,
+            statesByOwner,
+            statesByReason,
+            activeStateId: this.activeStateId,
+            queueLength: this.stateQueue.length,
+            stateDetails,
+        };
+    }
+}

package/dist/utils/securityOverlayManager.d.ts

@@ -0,0 +1,253 @@
+import type { MediatorAware, ProtectionMediator } from "../core/mediator/types";
+import { LoggableComponent } from "./base/LoggableComponent";
+/**
+ * Options for the security overlay
+ */
+export interface OverlayOptions {
+    /**
+     * Title to display in the overlay
+     */
+    title?: string;
+    /**
+     * Main message to display
+     */
+    message?: string;
+    /**
+     * Secondary message to display
+     */
+    secondaryMessage?: string;
+    /**
+     * Text color for the overlay
+     */
+    textColor?: string;
+    /**
+     * Background color for the overlay
+     */
+    backgroundColor?: string;
+    /**
+     * Z-index for the overlay (default: 2147483647)
+     */
+    zIndex?: string;
+    /**
+     * Whether to show a close button
+     */
+    showCloseButton?: boolean;
+    /**
+     * Text for the close button
+     */
+    closeButtonText?: string;
+    /**
+     * Callback when close button is clicked
+     */
+    onCloseButtonClick?: () => void;
+    /**
+     * Duration in milliseconds to show the overlay (0 for indefinite)
+     */
+    duration?: number;
+    /**
+     * Additional custom styles for the overlay
+     */
+    customStyles?: Record<string, string>;
+    /**
+     * Additional custom styles for the text
+     */
+    textStyles?: Record<string, string>;
+    /**
+     * Font size (ScreenshotStrategy - refactor)
+     */
+    fontSize?: string;
+    /**
+     * Additional HTML content to display in the overlay
+     */
+    additionalContent?: string;
+    /**
+     * Whether to block events (create an event blocker)
+     */
+    blockEvents?: boolean;
+    /**
+     * Whether to automatically restore the overlay if it's removed from the DOM
+     * @default true
+     */
+    autoRestore?: boolean;
+}
+/**
+ * Utility class to manage security overlays
+ */
+export declare class SecurityOverlayManager extends LoggableComponent implements MediatorAware {
+    private mediator;
+    private domObserver;
+    private overlays;
+    private activeOverlayId;
+    private overlayQueue;
+    private onElementsRemovedCallbacks;
+    /**
+     * Create a new SecurityOverlayManager
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(debugMode?: boolean);
+    /**
+     * Set the mediator to communicate with the other components
+     * @param mediator The protection mediator
+     */
+    setMediator(mediator: ProtectionMediator): void;
+    /**
+     * Check if an overlay with the same owner and type already exists
+     * @param owner The owner to check
+     * @param overlayType The overlay type to check
+     * @returns True if a matching overlay exists
+     */
+    private hasOverlayByOwnerAndType;
+    /**
+     * Handle overlay shown event
+     * @param event The protection event
+     */
+    private handleOverlayShown;
+    /**
+     * Handle overlay removed event
+     * @param event The protection event
+     */
+    private handleOverlayRemoved;
+    /**
+     * Handle overlay restored event
+     * @param event The protection event
+     */
+    private handleOverlayRestored;
+    /**
+     * Register a new overlay
+     * @param owner The strategy or component that owns this overlay
+     * @param overlayType The type of overlay (e.g., "screenshot", "devtools")
+     * @param options Options for the overlay
+     * @param priority Priority for display order (higher displays on top)
+     * @returns The ID of the registered overlay
+     */
+    registerOverlay(owner: string, overlayType: string, options: OverlayOptions, priority?: number): string;
+    /**
+     * Add an overlay to the queue
+     * @param overlayId ID of the overlay to add to queue
+     */
+    private addToQueue;
+    /**
+     * Show a specific overlay by ID
+     * @param overlayId ID of the overlay to show
+     * @returns True if the overlay was shown successfully
+     */
+    private showOverlayById;
+    /**
+     * Hide a specific overlay by ID without removing it from storage
+     * @param overlayId ID of the overlay to hide
+     * @param processQueue Whether to process the queue after hiding
+     * @returns True if the overlay was hidden successfully
+     */
+    private hideOverlayById;
+    /**
+     * Create overlay and blocker elements
+     * @param overlay The stored overlay information
+     * @returns Object containing the created elements
+     */
+    private createOverlayElements;
+    /**
+     * Remove a specific overlay by ID
+     * @param overlayId ID of the overlay to remove
+     * @returns True if the overlay was removed successfully
+     */
+    removeOverlayById(overlayId: string): boolean;
+    /**
+     * Remove all overlays for a specific owner
+     * @param owner The owner to remove overlays for
+     * @returns The number of overlays removed
+     */
+    removeOverlaysByOwner(owner: string): number;
+    /**
+     * Check and restore overlays for a specific owner
+     * @param owner The owner to check overlays for
+     * @returns The number of overlays restored
+     */
+    checkAndRestoreOverlaysByOwner(owner: string): number;
+    /**
+     * Create an overlay element
+     * @param options Options for the overlay
+     * @param owner The owner of the overlay (for data attribute)
+     * @returns The created overlay element
+     */
+    private createOverlay;
+    /**
+     * Create an event blocker that prevents interaction with the page
+     * @returns The created event blocker element
+     */
+    private createEventBlocker;
+    /**
+     * Set up DOM observer to detect when overlay elements are removed
+     * @param overlay The overlay to observe
+     */
+    private setupObserver;
+    /**
+     * Remove global event listeners that were added to document and window
+     */
+    private removeGlobalEventListeners;
+    /**
+     * Notify all callbacks when elements are removed
+     * @param removedElements The elements that were removed
+     */
+    private notifyElementsRemovedCallbacks;
+    /**
+     * Add a callback to be called when overlay elements are removed
+     * @param callback Callback function
+     */
+    addElementsRemovedCallback(callback: (removedElements: HTMLElement[]) => void): void;
+    /**
+     * Remove a callback
+     * @param callback Callback function to remove
+     */
+    removeElementsRemovedCallback(callback: (removedElements: HTMLElement[]) => void): void;
+    /**
+     * Get all overlays for a specific owner
+     * @param owner The owner to get overlays for
+     * @returns Array of overlay IDs
+     */
+    getOverlaysByOwner(owner: string): string[];
+    /**
+     * Get all active overlays
+     * @returns Array of active overlay IDs
+     */
+    getActiveOverlays(): string[];
+    /**
+     * Check if an overlay exists
+     * @param overlayId The overlay ID
+     * @returns True if the overlay exists
+     */
+    hasOverlay(overlayId: string): boolean;
+    /**
+     * Get the currently active overlay ID
+     * @returns The active overlay ID or null if none is active
+     */
+    getActiveOverlayId(): string | null;
+    /**
+     * Get the overlay queue
+     * @returns Array of overlay IDs in the queue
+     */
+    getOverlayQueue(): string[];
+    /**
+     * Clear all overlays
+     * @returns The number of overlays removed
+     */
+    clearAllOverlays(): number;
+    /**
+     * Get debug information about registered overlays
+     * @returns Object with debug information
+     */
+    getDebugInfo(): {
+        totalOverlays: number;
+        overlaysByOwner: Record<string, number>;
+        overlaysByType: Record<string, number>;
+        activeOverlayId: string | null;
+        queueLength: number;
+        overlayDetails: Array<{
+            id: string;
+            owner: string;
+            type: string;
+            isVisible: boolean;
+            priority: number;
+            createdAt: number;
+        }>;
+    };
+}