@tindalabs/shield 0.1.0

package/dist/otel.js

@@ -0,0 +1,83 @@
+import { ContentProtector } from '@/core/index.js';
+function emit(emitter, name, attrs) {
+    try {
+        emitter(name, attrs);
+    }
+    catch { /* never let telemetry crash the app */ }
+}
+/**
+ * Creates a ContentProtector with all callbacks wired to the provided SpanEmitter.
+ * Each security event fires a call to emitter(), which should create and immediately
+ * end a child span — so events are exported to Tempo without waiting for the
+ * long-lived navigation span to close.
+ *
+ * Any existing customHandlers in options are preserved and called after the emit.
+ */
+export function attachShieldToSpan(options, emitter) {
+    const existing = options.customHandlers ?? {};
+    const handlers = {
+        ...existing,
+        onDevToolsOpen(isOpen) {
+            emit(emitter, isOpen ? 'shield.devtools.opened' : 'shield.devtools.closed');
+            existing.onDevToolsOpen?.(isOpen);
+        },
+        onSelectionAttempt(event) {
+            emit(emitter, 'shield.selection.attempted');
+            existing.onSelectionAttempt?.(event);
+        },
+        onContextMenuAttempt(event) {
+            emit(emitter, 'shield.context_menu.attempted');
+            existing.onContextMenuAttempt?.(event);
+        },
+        onPrintAttempt(event) {
+            emit(emitter, 'shield.print.attempted');
+            existing.onPrintAttempt?.(event);
+        },
+        onKeyboardShortcutBlocked(event) {
+            emit(emitter, 'shield.keyboard_shortcut.blocked', {
+                'shield.keyboard.key': event.key,
+                'shield.keyboard.code': event.code,
+            });
+            existing.onKeyboardShortcutBlocked?.(event);
+        },
+        onClipboardAttempt(event, action) {
+            emit(emitter, `shield.clipboard.${action}`);
+            existing.onClipboardAttempt?.(event, action);
+        },
+        onScreenshotAttempt(event) {
+            emit(emitter, 'shield.screenshot.attempted');
+            existing.onScreenshotAttempt?.(event);
+        },
+        onExtensionDetected(id, name, risk) {
+            emit(emitter, '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(emitter, 'shield.frame.embedding.detected', {
+                    'shield.frame.external': isExternal,
+                });
+            }
+            existing.onFrameEmbeddingDetected?.(isEmbedded, isExternal);
+        },
+        onProtectionBypassed(method, event) {
+            emit(emitter, 'shield.protection.bypassed', {
+                'shield.bypass.method': method,
+            });
+            existing.onProtectionBypassed?.(method, event);
+        },
+        onContentHidden(reason, target) {
+            emit(emitter, 'shield.content.hidden', { 'shield.hidden.reason': reason });
+            existing.onContentHidden?.(reason, target);
+        },
+        onContentRestored(target) {
+            emit(emitter, 'shield.content.restored');
+            existing.onContentRestored?.(target);
+        },
+    };
+    return new ContentProtector({ ...options, customHandlers: handlers });
+}

package/dist/policy.d.ts

@@ -0,0 +1,98 @@
+import { ContentProtector } from './core/index.js';
+import type { AssessOptions, ShieldAssessment, ShieldSignals } from './types/assessment.js';
+import type { CustomEventHandlers, WatermarkOptions } from './types/index.js';
+import type { SpanEmitter } from './otel.js';
+/**
+ * Boolean strategy keys available in ContentProtectionOptions.
+ * Used to declare which strategies a PolicyRule should activate.
+ */
+export type StrategyKey = 'preventSelection' | 'preventContextMenu' | 'preventKeyboardShortcuts' | 'preventPrinting' | 'preventScreenshots' | 'enableWatermark' | 'preventDevTools' | 'preventClipboard' | 'preventEmbedding' | 'preventExtensions';
+/**
+ * Conditions that must all be satisfied for a PolicyRule to trigger.
+ * An empty condition always matches.
+ */
+export interface PolicyCondition {
+    /** Trigger when the assess() risk score is within the given range. */
+    riskScore?: {
+        /** Score must be >= this value. */
+        gte?: number;
+        /** Score must be < this value. */
+        lt?: number;
+    };
+    /** Trigger when all listed signal values match the assessment result. */
+    signals?: Partial<Record<keyof ShieldSignals, boolean>>;
+}
+/**
+ * A single policy rule: activate a set of strategies when a condition is met.
+ */
+export interface PolicyRule {
+    when: PolicyCondition;
+    /** Strategy keys to activate when the condition matches. */
+    enable: StrategyKey[];
+    /**
+     * Watermark options to apply when 'enableWatermark' is in `enable`.
+     * Pass a factory function to embed session-specific data (e.g. the
+     * assess() session token) into the watermark text — useful for tracing
+     * scraped content back to the session that extracted it.
+     */
+    watermarkOptions?: WatermarkOptions | ((assessment: ShieldAssessment) => WatermarkOptions);
+}
+export interface PolicyEngineOptions {
+    /** Ordered list of policy rules. All matching rules are merged. */
+    policies: PolicyRule[];
+    /** Element to protect. Defaults to document.body inside ContentProtector. */
+    targetElement?: HTMLElement | null;
+    /** Custom event handlers forwarded to ContentProtector. */
+    customHandlers?: CustomEventHandlers;
+    /**
+     * OTel span emitter. When provided, policy trigger events are emitted as
+     * span events and ContentProtector callbacks are wired via attachShieldToSpan.
+     */
+    spanEmitter?: SpanEmitter;
+    /** Options forwarded to the internal assess() call. */
+    assessOptions?: AssessOptions;
+    /**
+     * Override the assess function. Primarily useful for testing.
+     * Defaults to the built-in assess().
+     */
+    assessFn?: (options?: AssessOptions) => Promise<ShieldAssessment>;
+}
+export interface PolicyResult {
+    /** The assessment that was used to evaluate policies. */
+    assessment: ShieldAssessment;
+    /**
+     * The active ContentProtector, already started via protect().
+     * null when no policy rules matched (no protection was activated).
+     */
+    protector: ContentProtector | null;
+}
+/**
+ * Runs assess(), evaluates the provided policy rules against the result,
+ * and activates a ContentProtector with the union of all matched strategies.
+ *
+ * Protection is proportional to detected risk — legitimate sessions see no
+ * overhead; automation, headless browsers, and high-risk sessions trigger
+ * only the strategies that are warranted.
+ *
+ * @example
+ * const { assessment, protector } = await assessAndProtect(contentEl, {
+ *   policies: [
+ *     // Watermark all medium-risk sessions — embed session token for traceability
+ *     {
+ *       when: { riskScore: { gte: 0.3 } },
+ *       enable: ['enableWatermark'],
+ *       watermarkOptions: (a) => ({ text: `PROTECTED-${a.risk.flags.join(',')}` }),
+ *     },
+ *     // Full protection for confirmed automation
+ *     {
+ *       when: { signals: { 'shield.automation.headless': true } },
+ *       enable: ['preventSelection', 'preventClipboard', 'preventScreenshots'],
+ *     },
+ *   ],
+ *   spanEmitter: (name, attrs) => {
+ *     const span = getTracer().startSpan(name, { attributes: attrs }, getRouteContext());
+ *     span.end();
+ *   },
+ * });
+ */
+export declare function assessAndProtect(element: HTMLElement | null, options: PolicyEngineOptions): Promise<PolicyResult>;

package/dist/policy.js

@@ -0,0 +1,97 @@
+import { assess } from './assess.js';
+import { ContentProtector } from './core/index.js';
+import { attachShieldToSpan } from './otel.js';
+function matchesCondition(assessment, condition) {
+    if (condition.riskScore !== undefined) {
+        const { gte, lt } = condition.riskScore;
+        if (gte !== undefined && assessment.risk.score < gte)
+            return false;
+        if (lt !== undefined && assessment.risk.score >= lt)
+            return false;
+    }
+    if (condition.signals !== undefined) {
+        for (const [key, expected] of Object.entries(condition.signals)) {
+            if (assessment.signals[key] !== expected)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Runs assess(), evaluates the provided policy rules against the result,
+ * and activates a ContentProtector with the union of all matched strategies.
+ *
+ * Protection is proportional to detected risk — legitimate sessions see no
+ * overhead; automation, headless browsers, and high-risk sessions trigger
+ * only the strategies that are warranted.
+ *
+ * @example
+ * const { assessment, protector } = await assessAndProtect(contentEl, {
+ *   policies: [
+ *     // Watermark all medium-risk sessions — embed session token for traceability
+ *     {
+ *       when: { riskScore: { gte: 0.3 } },
+ *       enable: ['enableWatermark'],
+ *       watermarkOptions: (a) => ({ text: `PROTECTED-${a.risk.flags.join(',')}` }),
+ *     },
+ *     // Full protection for confirmed automation
+ *     {
+ *       when: { signals: { 'shield.automation.headless': true } },
+ *       enable: ['preventSelection', 'preventClipboard', 'preventScreenshots'],
+ *     },
+ *   ],
+ *   spanEmitter: (name, attrs) => {
+ *     const span = getTracer().startSpan(name, { attributes: attrs }, getRouteContext());
+ *     span.end();
+ *   },
+ * });
+ */
+export async function assessAndProtect(element, options) {
+    const assessment = await (options.assessFn ?? assess)(options.assessOptions);
+    const enabledStrategies = new Set();
+    let resolvedWatermarkOptions;
+    let matchedRules = 0;
+    for (const rule of options.policies) {
+        if (!matchesCondition(assessment, rule.when))
+            continue;
+        matchedRules++;
+        for (const key of rule.enable) {
+            enabledStrategies.add(key);
+        }
+        // Last matched rule's watermarkOptions wins
+        if (rule.watermarkOptions !== undefined && rule.enable.includes('enableWatermark')) {
+            resolvedWatermarkOptions = typeof rule.watermarkOptions === 'function'
+                ? rule.watermarkOptions(assessment)
+                : rule.watermarkOptions;
+        }
+    }
+    if (enabledStrategies.size === 0) {
+        options.spanEmitter?.('shield.policy.evaluated', {
+            'shield.policy.matched_rules': 0,
+            'shield.policy.risk_score': assessment.risk.score,
+            'shield.policy.protection_activated': false,
+        });
+        return { assessment, protector: null };
+    }
+    const protectionOptions = {
+        targetElement: element,
+        customHandlers: options.customHandlers,
+    };
+    for (const key of enabledStrategies) {
+        protectionOptions[key] = true;
+    }
+    if (resolvedWatermarkOptions !== undefined) {
+        protectionOptions.watermarkOptions = resolvedWatermarkOptions;
+    }
+    const protector = options.spanEmitter
+        ? attachShieldToSpan(protectionOptions, options.spanEmitter)
+        : new ContentProtector(protectionOptions);
+    options.spanEmitter?.('shield.policy.triggered', {
+        'shield.policy.matched_rules': matchedRules,
+        'shield.policy.risk_score': assessment.risk.score,
+        'shield.policy.enabled_strategies': [...enabledStrategies].join(','),
+        'shield.policy.protection_activated': true,
+    });
+    protector.protect();
+    return { assessment, protector };
+}

package/dist/strategies/AbstractStrategy.d.ts

@@ -0,0 +1,124 @@
+import type { ProtectionStrategy } from "../types";
+import type { MediatorAware, ProtectionMediator } from "../core/mediator/types";
+import { LoggableComponent } from "../utils/base/LoggableComponent";
+/**
+ * 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 extends LoggableComponent implements ProtectionStrategy, MediatorAware {
+    /** Alias of `COMPONENT_NAME` retained for the strategy public API (and used as the owner key in `eventManager` registrations). */
+    readonly STRATEGY_NAME: string;
+    protected mediator: ProtectionMediator | null;
+    protected isAppliedFlag: 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);
+    /**
+     * Set the mediator
+     * to communicate with the other components
+     */
+    setMediator(mediator: ProtectionMediator): void;
+    /**
+     * Apply the protection strategy
+     * Must be implemented by subclasses
+     */
+    abstract apply(): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/strategies/AbstractStrategy.js

@@ -0,0 +1,256 @@
+import { eventManager } from "../utils/eventManager";
+import { isBrowser } from "../utils/environment";
+import { LoggableComponent } from "../utils/base/LoggableComponent";
+/**
+ * Error types for protection strategies
+ */
+export var StrategyErrorType;
+(function (StrategyErrorType) {
+    StrategyErrorType["INITIALIZATION"] = "initialization";
+    StrategyErrorType["APPLICATION"] = "application";
+    StrategyErrorType["REMOVAL"] = "removal";
+    StrategyErrorType["EVENT_HANDLING"] = "event_handling";
+    StrategyErrorType["OPTION_UPDATE"] = "option_update";
+    StrategyErrorType["UNKNOWN"] = "unknown";
+})(StrategyErrorType || (StrategyErrorType = {}));
+/**
+ * Custom error class for protection strategies
+ */
+export class StrategyError extends Error {
+    /**
+     * 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, errorType, message, originalError) {
+        super(`[${strategyName}] ${message}${originalError instanceof Error ? `: ${originalError.message}` : ""}`);
+        this.strategyName = strategyName;
+        this.errorType = errorType;
+        this.originalError = originalError;
+        this.name = "StrategyError";
+        // Maintain the stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, StrategyError);
+        }
+    }
+}
+/**
+ * Abstract base class for protection strategies
+ * Implements common functionality to reduce duplication
+ */
+export class AbstractStrategy extends LoggableComponent {
+    /**
+     * Create a new strategy
+     * @param strategyName Unique name for the strategy
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(strategyName, debugMode = false) {
+        super(strategyName, debugMode);
+        this.mediator = null;
+        this.isAppliedFlag = false;
+        this.eventIds = [];
+        this.STRATEGY_NAME = strategyName;
+    }
+    /**
+     * Set the mediator
+     * to communicate with the other components
+     */
+    setMediator(mediator) {
+        this.mediator = mediator;
+        this.logger.log("Mediator set");
+    }
+    /**
+     * Remove the protection strategy
+     * Can be overridden by subclasses for custom cleanup
+     */
+    remove() {
+        try {
+            if (!this.isAppliedFlag) {
+                this.logger.log("Protection not applied");
+                return;
+            }
+            if (isBrowser()) {
+                // Remove all event listeners using EventManager
+                const removedCount = this.removeEventsByOwner();
+                // Clear the event IDs array
+                this.eventIds = [];
+                this.isAppliedFlag = false;
+                this.logger.log(`Protection removed (${removedCount} events)`);
+            }
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, "Failed to remove protection", error);
+        }
+    }
+    /**
+     * Check if the strategy is currently applied
+     */
+    isApplied() {
+        return this.isAppliedFlag;
+    }
+    /**
+     * Update strategy options
+     * Should be implemented by subclasses that support options
+     */
+    updateOptions(options) {
+        try {
+            // Default implementation just logs that the method is not implemented
+            this.logger.log("Method updateOptions not implemented", options);
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.OPTION_UPDATE, "Failed to update options", error);
+        }
+    }
+    /**
+     * Handle an error that occurred in the strategy
+     * @param errorType Type of error
+     * @param message Error message
+     * @param originalError Original error that was caught
+     */
+    handleError(errorType, message, originalError) {
+        const error = new StrategyError(this.STRATEGY_NAME, errorType, message, originalError);
+        if (this.debugMode) {
+            console.error(error);
+            if (error.originalError instanceof Error && error.originalError.stack) {
+                console.error("Original stack:", error.originalError.stack);
+            }
+        }
+        else {
+            console.error(error.message);
+        }
+    }
+    /**
+     * 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
+     */
+    safeExecute(operation, errorType, fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            this.handleError(errorType, `Error during ${operation}`, error);
+            return 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
+     */
+    async safeExecuteAsync(operation, errorType, fn) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            this.handleError(errorType, `Error during ${operation}`, error);
+            return 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
+     */
+    registerEvent(target, eventType, handler, options) {
+        if (!target || !isBrowser())
+            return "";
+        // Defensive check: ensure the provided target supports addEventListener
+        // This prevents runtime TypeError when non-DOM objects (Vue refs, selectors, etc.) are passed
+        // and provides a clearer StrategyError for easier debugging.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (typeof target.addEventListener !== "function") {
+            this.handleError(StrategyErrorType.EVENT_HANDLING, `Invalid event target for ${eventType} - target does not implement addEventListener`, new Error("target.addEventListener is not a function"));
+            return "";
+        }
+        try {
+            // Create a wrapped handler that includes error handling
+            const wrappedHandler = (event) => {
+                try {
+                    return handler(event);
+                }
+                catch (error) {
+                    this.handleError(StrategyErrorType.EVENT_HANDLING, `Error handling ${eventType} event`, error);
+                }
+            };
+            // Pass all options including priority to the eventManager
+            const eventId = eventManager.addEventListener(target, eventType, wrappedHandler, this.STRATEGY_NAME, options);
+            if (eventId) {
+                this.eventIds.push(eventId);
+                this.logger.log(`Registered ${eventType} event (ID: ${eventId})`);
+            }
+            return eventId;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.EVENT_HANDLING, `Failed to register ${eventType} event`, error);
+            return "";
+        }
+    }
+    /**
+     * Remove all event listeners for this strategy
+     * @returns The number of events removed
+     */
+    removeEventsByOwner() {
+        try {
+            const removedCount = eventManager.removeEventsByOwner(this.STRATEGY_NAME);
+            if (removedCount > 0) {
+                this.logger.log(`Removed ${removedCount} events by owner ID`);
+            }
+            return removedCount;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, "Failed to remove events by owner", error);
+            return 0;
+        }
+    }
+    /**
+     * 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 (!target || !isBrowser())
+            return 0;
+        try {
+            const removedCount = eventManager.removeAllEventsForTarget(target);
+            if (removedCount > 0) {
+                this.logger.log(`Removed ${removedCount} events from target`);
+            }
+            return removedCount;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, "Failed to remove events for target", error);
+            return 0;
+        }
+    }
+    /**
+     * 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
+     */
+    removeEventsBySelector(selector, eventType) {
+        if (!isBrowser())
+            return 0;
+        try {
+            const removedCount = eventManager.removeEventsBySelector(selector, eventType, this.STRATEGY_NAME);
+            if (removedCount > 0) {
+                this.logger.log(`Removed ${removedCount} ${eventType} events via selector "${selector}"`);
+            }
+            return removedCount;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, `Failed to remove events by selector "${selector}"`, error);
+            return 0;
+        }
+    }
+}