content-security-toolkit 1.0.1 → 1.0.2

package/README.md

@@ -1,5 +1,27 @@
 # Content Security Toolkit
 
+> ## ⚠️ Deprecated — use [`@tindalabs/shield`](https://www.npmjs.com/package/@tindalabs/shield) instead
+>
+> This package has been superseded by **[`@tindalabs/shield`](https://github.com/tindalabs/shield)**, which keeps the entire `ContentProtector` API and adds structured risk assessment (`assess()`), an OpenTelemetry integration (`attachShieldToSpan()`), a declarative policy engine (`assessAndProtect()`), and zero runtime dependencies.
+>
+> **Migrate in two lines:**
+>
+> ```bash
+> npm uninstall content-security-toolkit
+> npm install @tindalabs/shield
+> ```
+>
+> ```ts
+> // Before:  import { ContentProtector } from 'content-security-toolkit';
+> // After:   import { ContentProtector } from '@tindalabs/shield';
+> ```
+>
+> Every `ContentProtector` option you used here works identically in Shield. Full migration guide: [github.com/tindalabs/shield/blob/main/MIGRATION.md](https://github.com/tindalabs/shield/blob/main/MIGRATION.md). See also [DEPRECATED.md](./DEPRECATED.md).
+>
+> Existing installs continue to work — the package is **not** unpublished. Security fixes and new features land in Shield only.
+
+---
+
 [![npm version](https://img.shields.io/npm/v/content-security-toolkit.svg)](https://www.npmjs.com/package/content-security-toolkit) [![Build Status](https://github.com/Isonimus/content-security-toolkit/actions/workflows/publish.yml/badge.svg)](https://github.com/Isonimus/content-security-toolkit/actions) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 A comprehensive toolkit for implementing content security measures in web applications — lightweight, modular, and TypeScript-friendly.

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

@@ -0,0 +1,65 @@
+import type { ProtectionMediator } from "../../mediator/types";
+import type { ProtectionEvent, ProtectionEventType } from "../../mediator/protection-event";
+/**
+ * Abstract base class for all event handlers
+ */
+export declare abstract class BaseEventHandler {
+    protected mediator: ProtectionMediator;
+    protected readonly COMPONENT_NAME: string;
+    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;
+    /**
+     * Log a debug message
+     * @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;
+    /**
+     * 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;
+    /**
+     * 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/baseEventHandler.js

@@ -0,0 +1,99 @@
+/**
+ * Abstract base class for all event handlers
+ */
+export class BaseEventHandler {
+    /**
+     * 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) {
+        this.subscriptionIds = [];
+        this.mediator = mediator;
+        this.COMPONENT_NAME = componentName;
+        this.debugMode = debugMode;
+        this.initialize();
+        if (this.debugMode) {
+            this.log("Initialized and subscribed to events");
+        }
+    }
+    /**
+     * Log a debug message
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    log(message, ...args) {
+        if (this.debugMode) {
+            console.log(`${this.COMPONENT_NAME}: ${message}`, ...args);
+        }
+    }
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    warn(message, ...args) {
+        if (this.debugMode) {
+            console.warn(`${this.COMPONENT_NAME}: ${message}`, ...args);
+        }
+        else {
+            // In non-debug mode, only log the message without args for brevity
+            console.warn(`${this.COMPONENT_NAME}: ${message}`);
+        }
+    }
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    error(message, ...args) {
+        console.error(`${this.COMPONENT_NAME}: ${message}`, ...args);
+    }
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled) {
+        this.debugMode = enabled;
+        if (this.debugMode) {
+            this.log(`Debug mode ${enabled ? "enabled" : "disabled"}`);
+        }
+    }
+    /**
+     * 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/index.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/index.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/index.d.ts

@@ -2,3 +2,5 @@ export { ContentProtector } from './core/index.js';
 export * from './types/index.js';
 export * from './strategies/index.js';
 export * from './utils/index.js';
+export { attachShieldToSpan } from './otel.js';
+export type { SpanLike, SpanProvider } from './otel.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export { ContentProtector } from './core/index.js';
 export * from './types/index.js';
 export * from './strategies/index.js';
 export * from './utils/index.js';
+export { attachShieldToSpan } from './otel.js';

package/dist/otel.d.ts

@@ -0,0 +1,24 @@
+import { ContentProtector } from '@/core/index.js';
+import type { ContentProtectionOptions } from '@/types/index.js';
+/**
+ * Minimal span interface — matches @opentelemetry/api Span without requiring
+ * it as a dependency. Pass any object with addEvent() — including real OTel spans
+ * or a Blindspot route span from getRouteSpan().
+ */
+export interface SpanLike {
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+}
+export type SpanProvider = () => SpanLike | null | undefined;
+/**
+ * Creates a ContentProtector with all callbacks wired to OTel span events.
+ *
+ * Pass any existing customHandlers in options — they run after the span event
+ * is recorded, so UI state updates and span recording both happen.
+ *
+ * @example
+ * // With Blindspot:
+ * import { getRouteSpan } from '@tindalabs/blindspot-web';
+ * const protector = attachShieldToSpan(options, () => getRouteSpan());
+ * protector.protect();
+ */
+export declare function attachShieldToSpan(options: ContentProtectionOptions, spanProvider: SpanProvider): ContentProtector;

package/dist/otel.js

@@ -0,0 +1,87 @@
+import { ContentProtector } from '@/core/index.js';
+function emit(provider, name, attrs) {
+    try {
+        provider()?.addEvent(name, attrs);
+    }
+    catch { /* never let telemetry crash the app */ }
+}
+/**
+ * Creates a ContentProtector with all callbacks wired to OTel span events.
+ *
+ * Pass any existing customHandlers in options — they run after the span event
+ * is recorded, so UI state updates and span recording both happen.
+ *
+ * @example
+ * // With Blindspot:
+ * import { getRouteSpan } from '@tindalabs/blindspot-web';
+ * const protector = attachShieldToSpan(options, () => getRouteSpan());
+ * protector.protect();
+ */
+export function attachShieldToSpan(options, spanProvider) {
+    const existing = options.customHandlers ?? {};
+    const handlers = {
+        ...existing,
+        onDevToolsOpen(isOpen) {
+            emit(spanProvider, isOpen ? 'shield.devtools.opened' : 'shield.devtools.closed');
+            existing.onDevToolsOpen?.(isOpen);
+        },
+        onSelectionAttempt(event) {
+            emit(spanProvider, 'shield.selection.attempted');
+            existing.onSelectionAttempt?.(event);
+        },
+        onContextMenuAttempt(event) {
+            emit(spanProvider, 'shield.context_menu.attempted');
+            existing.onContextMenuAttempt?.(event);
+        },
+        onPrintAttempt(event) {
+            emit(spanProvider, 'shield.print.attempted');
+            existing.onPrintAttempt?.(event);
+        },
+        onKeyboardShortcutBlocked(event) {
+            emit(spanProvider, 'shield.keyboard_shortcut.blocked', {
+                'shield.keyboard.key': event.key,
+                'shield.keyboard.code': event.code,
+            });
+            existing.onKeyboardShortcutBlocked?.(event);
+        },
+        onClipboardAttempt(event, action) {
+            emit(spanProvider, `shield.clipboard.${action}`);
+            existing.onClipboardAttempt?.(event, action);
+        },
+        onScreenshotAttempt(event) {
+            emit(spanProvider, 'shield.screenshot.attempted');
+            existing.onScreenshotAttempt?.(event);
+        },
+        onExtensionDetected(id, name, risk) {
+            emit(spanProvider, 'shield.extension.detected', {
+                'shield.extension.id': id,
+                'shield.extension.name': name,
+                'shield.extension.risk': risk,
+            });
+            existing.onExtensionDetected?.(id, name, risk);
+        },
+        onFrameEmbeddingDetected(isEmbedded, isExternal) {
+            if (isEmbedded) {
+                emit(spanProvider, 'shield.frame.embedding.detected', {
+                    'shield.frame.external': isExternal,
+                });
+            }
+            existing.onFrameEmbeddingDetected?.(isEmbedded, isExternal);
+        },
+        onProtectionBypassed(method, event) {
+            emit(spanProvider, 'shield.protection.bypassed', {
+                'shield.bypass.method': method,
+            });
+            existing.onProtectionBypassed?.(method, event);
+        },
+        onContentHidden(reason, target) {
+            emit(spanProvider, 'shield.content.hidden', { 'shield.hidden.reason': reason });
+            existing.onContentHidden?.(reason, target);
+        },
+        onContentRestored(target) {
+            emit(spanProvider, 'shield.content.restored');
+            existing.onContentRestored?.(target);
+        },
+    };
+    return new ContentProtector({ ...options, customHandlers: handlers });
+}

package/dist/strategies/AbstractStrategy.mediator.d.ts

@@ -0,0 +1,162 @@
+import type { ProtectionStrategy } from "../types";
+import type { ProtectionMediator, ProtectionEventHandler, SubscriptionOptions } from "../core/mediator/types";
+import { ProtectionEventType } from "../core/mediator/protection-event";
+import type { EventDataMap } from "../core/mediator/eventDataTypes";
+/**
+ * Error types for protection strategies
+ */
+export declare enum StrategyErrorType {
+    INITIALIZATION = "initialization",
+    APPLICATION = "application",
+    REMOVAL = "removal",
+    EVENT_HANDLING = "event_handling",
+    OPTION_UPDATE = "option_update",
+    UNKNOWN = "unknown"
+}
+/**
+ * Custom error class for protection strategies
+ */
+export declare class StrategyError extends Error {
+    readonly strategyName: string;
+    readonly errorType: StrategyErrorType;
+    readonly originalError?: (Error | unknown) | undefined;
+    /**
+     * Create a new StrategyError
+     * @param strategyName Name of the strategy where the error occurred
+     * @param errorType Type of error that occurred
+     * @param message Error message
+     * @param originalError Original error that was caught (if any)
+     */
+    constructor(strategyName: string, errorType: StrategyErrorType, message: string, originalError?: (Error | unknown) | undefined);
+}
+/**
+ * Abstract base class for protection strategies
+ * Implements common functionality to reduce duplication
+ */
+export declare abstract class AbstractStrategy implements ProtectionStrategy {
+    protected mediator: ProtectionMediator | null;
+    protected subscriptionIds: string[];
+    readonly STRATEGY_NAME: string;
+    protected isAppliedFlag: boolean;
+    protected debugMode: boolean;
+    protected eventIds: string[];
+    /**
+     * Create a new strategy
+     * @param strategyName Unique name for the strategy
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(strategyName: string, debugMode?: boolean);
+    /**
+     * Apply the protection strategy
+     * Must be implemented by subclasses
+     */
+    abstract apply(): void;
+    /**
+     * Set the mediator for this strategy
+     * This connects the strategy to the event system
+     * @param mediator The protection mediator instance
+     */
+    setMediator(mediator: ProtectionMediator): void;
+    /**
+     * Helper method for subscribing to events
+     * Tracks subscription IDs for cleanup
+     */
+    protected subscribe(eventType: ProtectionEventType, handler: ProtectionEventHandler, options?: SubscriptionOptions): string;
+    /**
+     * Helper method for publishing events
+     */
+    protected publishEvent<T extends ProtectionEventType>(eventType: T, data?: EventDataMap[T]): void;
+    /**
+     * Remove the protection strategy
+     * Can be overridden by subclasses for custom cleanup
+     */
+    remove(): void;
+    /**
+     * Check if the strategy is currently applied
+     */
+    isApplied(): boolean;
+    /**
+     * Update strategy options
+     * Should be implemented by subclasses that support options
+     */
+    updateOptions(options: Record<string, unknown>): void;
+    /**
+     * Get the debug mode status
+     */
+    isDebugEnabled(): boolean;
+    /**
+     * Set debug mode
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Handle an error that occurred in the strategy
+     * @param errorType Type of error
+     * @param message Error message
+     * @param originalError Original error that was caught
+     */
+    protected handleError(errorType: StrategyErrorType, message: string, originalError?: unknown): void;
+    /**
+     * 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;
+    /**
+     * Execute a function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Function to execute
+     * @returns The result of the function or undefined if an error occurred
+     */
+    protected safeExecute<T>(operation: string, errorType: StrategyErrorType, fn: () => T): T | undefined;
+    /**
+     * Execute an async function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Async function to execute
+     * @returns Promise resolving to the result of the function or undefined if an error occurred
+     */
+    protected safeExecuteAsync<T>(operation: string, errorType: StrategyErrorType, fn: () => Promise<T>): Promise<T | undefined>;
+    /**
+     * Register an event with the EventManager
+     * @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 options Additional options for the event listener
+     * @returns The ID of the registered event
+     */
+    protected registerEvent(target: EventTarget | null, eventType: string, handler: EventListener, options?: AddEventListenerOptions & {
+        priority?: number;
+        id?: string;
+    }): string;
+    /**
+     * Remove all event listeners for this strategy
+     * @returns The number of events removed
+     */
+    protected removeEventsByOwner(): number;
+    /**
+     * Remove all event listeners for a specific target
+     * @param target The target to remove events from
+     * @returns The number of events removed
+     */
+    protected removeAllEventsForTarget(target: EventTarget | null): number;
+    /**
+     * Remove event listeners by CSS selector
+     * @param selector CSS selector to match elements
+     * @param eventType Type of event to remove
+     * @returns The number of events removed
+     */
+    protected removeEventsBySelector(selector: string, eventType: string): number;
+}