@tindalabs/shield 0.1.0

package/dist/strategies/SelectionStrategy.js

@@ -0,0 +1,216 @@
+import { isBrowser, isMobile } from "../utils/environment";
+import { AbstractStrategy, StrategyErrorType } from "./AbstractStrategy";
+/**
+ * Strategy for preventing text selection
+ */
+export class SelectionStrategy extends AbstractStrategy {
+    /**
+     * Create a new SelectionStrategy
+     * @param targetElement Element to protect (defaults to document.body)
+     * @param customHandler Optional custom handler for selection attempts
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(targetElement, customHandler, debugMode = false) {
+        super("SelectionStrategy", debugMode);
+        this.targetElement = null;
+        this.styleElement = null;
+        this.preventDrag = true;
+        this.targetElement = targetElement || (isBrowser() ? document.body : null);
+        this.customHandler = customHandler;
+        this.selectionHandler = this.handleSelection.bind(this);
+        this.dragHandler = this.handleDrag.bind(this);
+        this.log("Initialized with target:", this.targetElement === document.body ? "document.body" : "custom element");
+    }
+    /**
+     * Handle selection event
+     */
+    handleSelection(e) {
+        return (this.safeExecute("handleSelection", StrategyErrorType.EVENT_HANDLING, () => {
+            this.log("Selection attempt detected", {
+                eventType: e.type,
+                target: e.target,
+            });
+            // Call custom handler if provided
+            if (this.customHandler) {
+                this.customHandler(e);
+            }
+            if (isBrowser() && window.getSelection) {
+                const selection = window.getSelection();
+                if (selection) {
+                    selection.removeAllRanges();
+                }
+            }
+            e.preventDefault();
+            e.stopPropagation();
+            return false;
+        }) || false);
+    }
+    /**
+     * Handle drag event
+     */
+    handleDrag(e) {
+        this.safeExecute("handleDrag", StrategyErrorType.EVENT_HANDLING, () => {
+            this.log("Drag attempt detected", {
+                eventType: e.type,
+                target: e.target,
+            });
+            // Call custom handler if provided
+            if (this.customHandler) {
+                this.customHandler(e);
+            }
+            e.preventDefault();
+            e.stopPropagation();
+        });
+    }
+    /**
+     * Inject CSS to prevent selection
+     */
+    injectSelectionStyles() {
+        this.safeExecute("injectSelectionStyles", StrategyErrorType.APPLICATION, () => {
+            if (!isBrowser())
+                return;
+            this.styleElement = document.createElement("style");
+            this.styleElement.setAttribute("type", "text/css");
+            this.styleElement.setAttribute("data-content-security", "selection-blocker");
+            const selector = this.targetElement === document.body ? "body" : ".protected-content";
+            const css = `
+        ${selector} {
+          -webkit-user-select: none;
+          -moz-user-select: none;
+          -ms-user-select: none;
+          user-select: none;
+        }
+        
+        ${selector} ::selection {
+          background: transparent;
+        }
+      `;
+            this.styleElement.textContent = css;
+            document.head.appendChild(this.styleElement);
+            // Add class if not targeting body
+            if (this.targetElement !== document.body) {
+                this.targetElement?.classList.add("protected-content");
+            }
+            this.log("Selection-blocking CSS injected");
+        });
+    }
+    /**
+     * Remove selection-blocking CSS
+     */
+    removeSelectionStyles() {
+        this.safeExecute("removeSelectionStyles", StrategyErrorType.REMOVAL, () => {
+            if (!this.styleElement || !isBrowser())
+                return;
+            try {
+                document.head.removeChild(this.styleElement);
+                this.styleElement = null;
+                // Remove class if not targeting body
+                if (this.targetElement !== document.body) {
+                    this.targetElement?.classList.remove("protected-content");
+                }
+                this.log("Selection-blocking CSS removed");
+            }
+            catch (error) {
+                this.handleError(StrategyErrorType.REMOVAL, "Error removing selection styles", error);
+                // Try to find and remove by selector as fallback
+                try {
+                    const styles = document.querySelectorAll('style[data-content-security="selection-blocker"]');
+                    styles.forEach((style) => {
+                        if (style.parentNode) {
+                            style.parentNode.removeChild(style);
+                        }
+                    });
+                    this.styleElement = null;
+                    if (styles.length > 0) {
+                        this.log(`Removed ${styles.length} selection-blocking styles by selector`);
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                }
+                catch (fallbackError) {
+                    // Last resort fallback
+                    this.styleElement = null;
+                }
+            }
+        });
+    }
+    /**
+     * Apply selection protection
+     */
+    apply() {
+        this.safeExecute("apply", StrategyErrorType.APPLICATION, () => {
+            if (this.isAppliedFlag || !this.targetElement)
+                return;
+            this.log("Applying selection protection", {
+                targetElement: this.targetElement === document.body ? "document.body" : "custom element",
+                hasCustomHandler: !!this.customHandler,
+                preventDrag: this.preventDrag,
+                isMobile: isMobile(),
+            });
+            // Add CSS
+            this.injectSelectionStyles();
+            // Add event listeners using the registerEvent method from AbstractStrategy
+            this.registerEvent(this.targetElement, "selectstart", this.selectionHandler);
+            this.registerEvent(this.targetElement, "mousedown", this.selectionHandler, { capture: true });
+            // Disable drag
+            if (this.preventDrag) {
+                this.registerEvent(this.targetElement, "dragstart", this.dragHandler);
+            }
+            this.isAppliedFlag = true;
+        });
+    }
+    /**
+     * Remove selection protection
+     */
+    remove() {
+        this.safeExecute("remove", StrategyErrorType.REMOVAL, () => {
+            if (!this.isAppliedFlag || !this.targetElement)
+                return;
+            // Remove CSS
+            this.removeSelectionStyles();
+            // Remove all events for this owner using the parent class method
+            this.removeEventsByOwner();
+            // Second attempt - try direct DOM removal as fallback
+            try {
+                if (this.targetElement) {
+                    this.targetElement.removeEventListener("selectstart", this.selectionHandler);
+                    this.targetElement.removeEventListener("mousedown", this.selectionHandler, { capture: true });
+                    this.targetElement.removeEventListener("dragstart", this.dragHandler);
+                    this.log("Removed events via direct DOM API");
+                }
+            }
+            catch (domError) {
+                // Ignore errors in direct DOM removal
+                this.handleError(StrategyErrorType.REMOVAL, "Error in fallback DOM removal", domError);
+            }
+            // Clear tracked event IDs
+            this.eventIds = [];
+            this.isAppliedFlag = false;
+            this.log("Selection protection removed");
+        });
+    }
+    /**
+     * Update selection protection options
+     * @param options New options for selection protection
+     */
+    updateOptions(options) {
+        this.safeExecute("updateOptions", StrategyErrorType.OPTION_UPDATE, () => {
+            this.log("Updating options", options);
+            // Update debug mode if specified
+            if (options.debugMode !== undefined) {
+                this.setDebugMode(!!options.debugMode);
+            }
+            // Update preventDrag if specified
+            if (options.preventDrag !== undefined) {
+                const oldPreventDrag = this.preventDrag;
+                this.preventDrag = !!options.preventDrag;
+                // If we need to update the applied strategy
+                if (this.isAppliedFlag && oldPreventDrag !== this.preventDrag) {
+                    // Remove and reapply to update event listeners
+                    this.remove();
+                    this.apply();
+                    this.log("Reapplied with updated options");
+                }
+            }
+        });
+    }
+}

package/dist/strategies/WatermarkStrategy.d.ts

@@ -0,0 +1,56 @@
+import type { WatermarkOptions } from "../types";
+import { AbstractStrategy } from "./AbstractStrategy";
+/**
+ * Strategy for adding watermarks to content
+ */
+export declare class WatermarkStrategy extends AbstractStrategy {
+    private targetElement;
+    private options;
+    private watermarkElements;
+    private domObserver;
+    private isFullPageWatermark;
+    private watermarkContainer;
+    private osInfo;
+    /**
+     * Unique per-instance id. Watermark containers are tagged with this so that
+     * cleanup queries only ever match THIS instance's container. Without it, two
+     * concurrent WatermarkStrategy instances (e.g. two ContentProtectors on the
+     * same or nested elements) would delete each other's containers, and each
+     * auto-restore would re-trigger the other's observer — an infinite
+     * MutationObserver loop that freezes the page.
+     */
+    private readonly instanceId;
+    /**
+     * Create a new WatermarkStrategy
+     * @param targetElement Element to watermark (defaults to document.body)
+     * @param options Watermark options
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(options?: WatermarkOptions, targetElement?: HTMLElement | null, debugMode?: boolean);
+    /**
+     * Create watermarks
+     */
+    private createWatermarks;
+    /**
+     * Set up DOM observer to detect watermark removal
+     */
+    private setupObserver;
+    /**
+     * Remove watermark elements
+     */
+    private removeWatermarkElements;
+    /**
+     * Apply watermark protection
+     */
+    apply(): void;
+    /**
+     * Remove watermark protection
+     * Override the base implementation to handle additional cleanup
+     */
+    remove(): void;
+    /**
+     * Update watermark options
+     * @param options New watermark options
+     */
+    updateOptions(options: Record<string, unknown>): void;
+}

package/dist/strategies/WatermarkStrategy.js

@@ -0,0 +1,287 @@
+import { DomObserver } from "../utils/DOMObserver";
+import { isBrowser, getOS } from "../utils/environment";
+import { AbstractStrategy, StrategyErrorType } from "./AbstractStrategy";
+/**
+ * Strategy for adding watermarks to content
+ */
+export class WatermarkStrategy extends AbstractStrategy {
+    /**
+     * Create a new WatermarkStrategy
+     * @param targetElement Element to watermark (defaults to document.body)
+     * @param options Watermark options
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(options, targetElement, debugMode = false) {
+        super("WatermarkStrategy", debugMode);
+        this.targetElement = null;
+        this.watermarkElements = [];
+        this.domObserver = null;
+        this.isFullPageWatermark = false;
+        this.watermarkContainer = null;
+        /**
+         * Unique per-instance id. Watermark containers are tagged with this so that
+         * cleanup queries only ever match THIS instance's container. Without it, two
+         * concurrent WatermarkStrategy instances (e.g. two ContentProtectors on the
+         * same or nested elements) would delete each other's containers, and each
+         * auto-restore would re-trigger the other's observer — an infinite
+         * MutationObserver loop that freezes the page.
+         */
+        this.instanceId = `wm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        this.targetElement = targetElement || (isBrowser() ? document.body : null);
+        this.options = {
+            text: "CONFIDENTIAL",
+            opacity: 0.15,
+            density: 3,
+            ...options,
+        };
+        this.osInfo = getOS();
+        this.watermarkElements = [];
+        // Determine if we're doing a full-page watermark
+        if (isBrowser() && this.targetElement === document.body) {
+            this.isFullPageWatermark = true;
+        }
+        this.log("Initialized with OS:", this.osInfo, "Full-page:", this.isFullPageWatermark);
+    }
+    /**
+     * Create watermarks
+     */
+    createWatermarks() {
+        return this.safeExecute("createWatermarks", StrategyErrorType.APPLICATION, () => {
+            if (!this.targetElement || !isBrowser())
+                return;
+            // Check if THIS instance's watermark container already exists. Scoped to
+            // instanceId so we never remove a container owned by another concurrent
+            // WatermarkStrategy (doing so would start a cross-instance restore loop).
+            const existingContainer = document.querySelector(`[data-watermark-instance="${this.instanceId}"]`);
+            if (existingContainer) {
+                this.log("Watermark container already exists, removing first");
+                if (existingContainer.parentNode) {
+                    existingContainer.parentNode.removeChild(existingContainer);
+                }
+            }
+            // Clear any existing watermarks
+            this.removeWatermarkElements();
+            // Calculate density
+            const density = Math.min(Math.max(this.options.density || 3, 1), 10);
+            const rows = density * 3;
+            const cols = density * 3;
+            // Create watermark container
+            const container = document.createElement("div");
+            container.className = "content-security-watermark-container";
+            container.setAttribute("data-watermark-id", `watermark-${Date.now()}`);
+            container.setAttribute("data-watermark-instance", this.instanceId);
+            this.watermarkContainer = container;
+            // Set container styles based on whether it's full-page or element-specific
+            if (this.isFullPageWatermark) {
+                // Full-page watermark (fixed position covering viewport)
+                Object.assign(container.style, {
+                    position: "fixed",
+                    top: "0",
+                    left: "0",
+                    width: "100%",
+                    height: "100%",
+                    overflow: "hidden",
+                    pointerEvents: "none",
+                    zIndex: "2147483647", // Max z-index
+                    userSelect: "none",
+                });
+            }
+            else {
+                // Element-specific watermark
+                // Get the computed style of the target element
+                const targetStyle = window.getComputedStyle(this.targetElement);
+                const targetPosition = targetStyle.position;
+                // If the target element doesn't have a position set, we need to set it to relative
+                // so that our absolutely positioned watermark container stays within it
+                if (targetPosition === "static") {
+                    this.targetElement.style.position = "relative";
+                }
+                Object.assign(container.style, {
+                    position: "absolute",
+                    top: "0",
+                    left: "0",
+                    width: "100%",
+                    height: "100%",
+                    overflow: "hidden",
+                    pointerEvents: "none",
+                    zIndex: "999", // High z-index but not max to avoid breaking page layout
+                    userSelect: "none",
+                });
+            }
+            // Generate timestamp and user info for watermark
+            const timestamp = new Date().toISOString();
+            const userInfo = this.options.userId ? ` - User: ${this.options.userId}` : "";
+            const watermarkText = `${this.options.text}${userInfo} - ${timestamp}`;
+            // Create watermark pattern
+            for (let i = 0; i < rows; i++) {
+                for (let j = 0; j < cols; j++) {
+                    const watermark = document.createElement("div");
+                    watermark.className = "content-security-watermark";
+                    watermark.textContent = watermarkText;
+                    // Position watermark - use % for element-specific watermarks instead of vh/vw
+                    const positionUnit = this.isFullPageWatermark ? "vh" : "%";
+                    const horizontalUnit = this.isFullPageWatermark ? "vw" : "%";
+                    Object.assign(watermark.style, {
+                        position: "absolute",
+                        top: `${(i * 100) / rows}${positionUnit}`,
+                        left: `${(j * 100) / cols}${horizontalUnit}`,
+                        transform: "rotate(-45deg) translateX(-30%) translateY(-200%)",
+                        transformOrigin: "center",
+                        opacity: String(this.options.opacity || 0.15),
+                        fontSize: this.isFullPageWatermark ? "16px" : "14px", // Slightly smaller for element watermarks
+                        color: "rgba(0, 0, 0, 0.7)",
+                        whiteSpace: "nowrap",
+                        pointerEvents: "none",
+                        userSelect: "none",
+                        ...this.options.style,
+                    });
+                    container.appendChild(watermark);
+                    this.watermarkElements.push(watermark);
+                }
+            }
+            // Add container to target
+            this.targetElement.appendChild(container);
+            this.watermarkElements.push(container);
+            this.log("Created watermark container with", this.watermarkElements.length - 1, "watermarks");
+            // Set up observer to detect if watermarks are removed
+            this.setupObserver();
+        });
+    }
+    /**
+     * Set up DOM observer to detect watermark removal
+     */
+    setupObserver() {
+        return this.safeExecute("setupObserver", StrategyErrorType.APPLICATION, () => {
+            if (!this.targetElement || !isBrowser())
+                return;
+            // Create a handler for element removal
+            const handleElementsRemoved = (removedElements) => {
+                this.log("Watermark elements removed from DOM", removedElements);
+                // Only restore if auto-restore is enabled
+                if (this.isAppliedFlag) {
+                    this.log("Auto-restoring watermarks");
+                    // Restore the watermarks
+                    this.createWatermarks();
+                }
+            };
+            // Create a new observer if needed
+            if (!this.domObserver) {
+                this.domObserver = new DomObserver({
+                    targetElement: this.targetElement,
+                    elementsToWatch: this.watermarkContainer ? [this.watermarkContainer] : [],
+                    onElementsRemoved: handleElementsRemoved,
+                    observeSubtree: true,
+                    debugMode: this.debugMode,
+                    name: "WatermarkStrategy",
+                });
+            }
+            else {
+                // Update the elements to watch
+                this.domObserver.updateElementsToWatch(this.watermarkContainer ? [this.watermarkContainer] : []);
+            }
+            // Start observing
+            this.domObserver.startObserving();
+            this.log("DOM observer set up to detect watermark removal");
+        });
+    }
+    /**
+     * Remove watermark elements
+     */
+    removeWatermarkElements() {
+        return this.safeExecute("removeWatermarkElements", StrategyErrorType.REMOVAL, () => {
+            if (!isBrowser())
+                return;
+            // First, try to remove by container reference
+            if (this.watermarkContainer && this.watermarkContainer.parentNode) {
+                this.watermarkContainer.parentNode.removeChild(this.watermarkContainer);
+                this.watermarkContainer = null;
+            }
+            // Then try to remove individual elements
+            for (const element of this.watermarkElements) {
+                if (element.parentNode) {
+                    element.parentNode.removeChild(element);
+                }
+            }
+            // Also try to remove by instance id in case references were lost. Scoped
+            // to this instance so we never tear down another concurrent strategy's
+            // watermark (which would trigger its auto-restore observer in a loop).
+            const containers = document.querySelectorAll(`[data-watermark-instance="${this.instanceId}"]`);
+            containers.forEach((container) => {
+                if (container.parentNode) {
+                    container.parentNode.removeChild(container);
+                }
+            });
+            // If we modified the target element's position, restore it
+            if (!this.isFullPageWatermark && this.targetElement) {
+                // Only remove the position if we added it
+                // This is a simplification - ideally we'd store the original position
+                if (this.targetElement.style.position === "relative") {
+                    this.targetElement.style.position = "";
+                }
+            }
+            this.watermarkElements = [];
+            this.log("Removed all watermark elements");
+        });
+    }
+    /**
+     * Apply watermark protection
+     */
+    apply() {
+        return this.safeExecute("apply", StrategyErrorType.APPLICATION, () => {
+            if (this.isAppliedFlag) {
+                this.log("Already applied, skipping");
+                return;
+            }
+            this.log("Applying watermark protection", {
+                text: this.options.text,
+                opacity: this.options.opacity,
+                density: this.options.density,
+                userId: this.options.userId,
+                isFullPage: this.isFullPageWatermark,
+                os: this.osInfo.name,
+            });
+            this.createWatermarks();
+            this.isAppliedFlag = true;
+        });
+    }
+    /**
+     * Remove watermark protection
+     * Override the base implementation to handle additional cleanup
+     */
+    remove() {
+        return this.safeExecute("remove", StrategyErrorType.REMOVAL, () => {
+            if (!this.isAppliedFlag) {
+                this.log("Not applied, skipping removal");
+                return;
+            }
+            if (this.domObserver) {
+                this.domObserver.stopObserving();
+                this.domObserver = null;
+                this.log("DOM observer stopped");
+            }
+            this.removeWatermarkElements();
+            this.isAppliedFlag = false;
+            this.log("Watermark protection removed");
+        });
+    }
+    /**
+     * Update watermark options
+     * @param options New watermark options
+     */
+    updateOptions(options) {
+        return this.safeExecute("updateOptions", StrategyErrorType.OPTION_UPDATE, () => {
+            const typedOptions = options;
+            this.log("Updating options", typedOptions);
+            this.options = {
+                ...this.options,
+                ...typedOptions,
+            };
+            if (this.isAppliedFlag) {
+                // Reapply with new options
+                this.remove();
+                this.apply();
+                this.log("Reapplied watermarks with updated options");
+            }
+        });
+    }
+}

package/dist/strategies/index.d.ts

@@ -0,0 +1,10 @@
+export * from './KeyboardStrategy';
+export * from './ContextMenuStrategy';
+export * from './PrintStrategy';
+export * from './WatermarkStrategy';
+export * from './SelectionStrategy';
+export * from './DevToolsStrategy';
+export * from './ScreenshotStrategy';
+export * from './ExtensionStrategy';
+export * from './IFrameStrategy';
+export * from './ClipboardStrategy';

package/dist/strategies/index.js

@@ -0,0 +1,11 @@
+// BARREL FILE
+export * from './KeyboardStrategy';
+export * from './ContextMenuStrategy';
+export * from './PrintStrategy';
+export * from './WatermarkStrategy';
+export * from './SelectionStrategy';
+export * from './DevToolsStrategy';
+export * from './ScreenshotStrategy';
+export * from './ExtensionStrategy';
+export * from './IFrameStrategy';
+export * from './ClipboardStrategy';

package/dist/types/assessment.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Signal keys produced by assess(). All keys follow the shield.* OTel namespace
+ * so they can be attached directly to Blindspot / OpenTelemetry spans.
+ */
+export interface ShieldSignals {
+    /** DevTools panel is open in the current tab. */
+    'shield.devtools.open': boolean;
+    /** navigator.webdriver is set — Selenium, Playwright, Puppeteer, etc. */
+    'shield.automation.webdriver': boolean;
+    /** Browser is running in headless mode (no visible UI). */
+    'shield.automation.headless': boolean;
+    /** Page is embedded inside a cross-origin or unauthorized iframe. */
+    'shield.frame.embedded': boolean;
+    /** At least one known browser extension has been detected. */
+    'shield.extension.detected': boolean;
+    /** Comma-separated list of detected extension names (empty string if none). */
+    'shield.extension.names': string;
+}
+export interface ShieldRisk {
+    /** Normalised threat score in the [0, 1] range. */
+    score: number;
+    /** Machine-readable flag codes for each active threat. */
+    flags: string[];
+}
+/**
+ * Structured result returned by assess().
+ */
+export interface ShieldAssessment {
+    signals: ShieldSignals;
+    risk: ShieldRisk;
+    /**
+     * OTel-compatible span attributes.  Only truthy / non-default signal values
+     * are included so spans stay lean.  Attach these directly to a Blindspot
+     * span via span.setAttributes(result.spanAttributes).
+     */
+    spanAttributes: Record<string, string | boolean | number>;
+}
+/**
+ * Options for the assess() call.
+ */
+export interface AssessOptions {
+    /**
+     * Run DevTools detection. Slightly slower (async timing-based).
+     * @default true
+     */
+    devtools?: boolean;
+    /**
+     * Run browser-extension detection (async DOM scan).
+     * @default true
+     */
+    extensions?: boolean;
+    /**
+     * Maximum milliseconds to wait for async detections before resolving.
+     * @default 400
+     */
+    timeout?: number;
+    /**
+     * Inline extension config to check against. If omitted, uses the built-in
+     * signatures bundled with Shield.
+     */
+    extensionConfig?: import('./index.js').ExtensionConfig[];
+}

package/dist/types/assessment.js

@@ -0,0 +1 @@
+export {};