content-security-toolkit 1.0.0 → 1.0.2

package/README.md

@@ -1,15 +1,45 @@
 # Content Security Toolkit
 
-A comprehensive toolkit for implementing content security measures in web applications.
+> ## ⚠️ 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.
 
 ## Features
 
-- Prevent keyboard shortcuts (Ctrl+P, Ctrl+S, etc.)
-- Disable context menu (right-click)
-- Block printing attempts
-- Add watermarks to content
-- Works across desktop and mobile browsers
-- Highly configurable and extensible
+- Developer tools detection and response (DevTools detection)
+- Screenshot detection and response (blur, warnings, callbacks)
+- Watermarking with automatic regeneration (MutationObserver-protected)
+- Keyboard shortcut prevention (copy/print/inspect shortcuts)
+- Context menu blocking
+- Print prevention and watermark-on-print support
+- Selection / copy prevention
+- Extension detection (detect suspicious browser extensions)
+- Frame embedding protection (prevent unauthorized iframe embedding)
+- Modular, strategy-based architecture — enable/disable strategies independently
+- TypeScript typings, tests, and CI-ready workflow
+- Lightweight and easy to integrate into web apps
 
 ## Installation
 
@@ -17,7 +47,102 @@ A comprehensive toolkit for implementing content security measures in web applic
 npm install content-security-toolkit
 # or
 yarn add content-security-toolkit
-
+```
+
+## Usage
+
+### Simple usage (quick start)
+
+```javascript
+import { ContentProtector } from 'content-security-toolkit'
+
+// Protect the whole document with sensible defaults
+const protector = new ContentProtector()
+protector.protect()
+
+// Later...
+protector.unprotect()
+protector.dispose()
+```
+
+### Custom usage (advanced configuration)
+
+```javascript
+import { ContentProtector } from 'content-security-toolkit'
+
+const protector = new ContentProtector({
+  targetElement: '#viewer',            // CSS selector or HTMLElement
+  enableWatermark: true,
+  watermarkOptions: {
+    text: 'CONFIDENTIAL',
+    opacity: 0.12,
+    density: 3,
+  },
+  preventDevTools: true,
+  preventScreenshots: true,
+  preventEmbedding: true,
+  debugMode: false,
+  // Optional callbacks
+  customHandlers: {
+    onDevToolsDetected: () => console.warn('DevTools opened'),
+    onScreenshotDetected: () => alert('Screenshot detected'),
+  },
+})
+
+protector.protect()
+```
+
+### Framework quick examples
+
+React (hooks):
+
+```jsx
+import React, { useEffect } from 'react'
+import { ContentProtector } from 'content-security-toolkit'
+
+function Viewer() {
+  useEffect(() => {
+    const protector = new ContentProtector({ enableWatermark: true })
+    protector.protect()
+    return () => protector.dispose()
+  }, [])
+
+  return <div id="protected-content">Protected content</div>
+}
+```
+
+Vue 3 (Composition API):
+
+```js
+import { onMounted, onUnmounted } from 'vue'
+import { ContentProtector } from 'content-security-toolkit'
+
+export default {
+  setup() {
+    let protector
+    onMounted(() => {
+      protector = new ContentProtector({ targetElement: '#protected-content' })
+      protector.protect()
+    })
+    onUnmounted(() => protector?.dispose())
+  },
+}
+```
+
+### API highlights
+
+- `ContentProtector.protect()` — enable protection
+- `ContentProtector.unprotect()` — disable protection
+- `ContentProtector.dispose()` — cleanup resources
+- `ContentProtector.getStrategy(name)` — access a strategy instance for advanced control
+- Options include: `targetElement`, `enableWatermark`, `watermarkOptions`, `preventDevTools`, `preventScreenshots`, `preventEmbedding`, `debugMode`, `customHandlers`
+
+_For full examples, see `examples/` and `examples/advanced/advanced_example.ts`._
+### Where to start
+
+- Use the simple example to get protection running quickly.
+- Add `customHandlers` and `watermarkOptions` to tailor behaviour.
+- See `examples/` for runnable demos and the `src/` folder for strategy implementations.
 
 Content Security Toolkit is a comprehensive JavaScript/TypeScript library designed to protect sensitive web content from unauthorized copying, extraction, and distribution. It implements multiple layers of protection strategies that work together to safeguard digital content while maintaining a good user experience for legitimate users.
 
@@ -42,46 +167,56 @@ This architecture allows for flexible configuration and easy extension with new
 
 **Implementation Details**:
 
-- Intercepts key combinations like Ctrl+C, Ctrl+P, Ctrl+S, Ctrl+Shift+I
+- Intercepts key combinations like Ctrl/Cmd+C, Ctrl/Cmd+P, Ctrl/Cmd+S, Ctrl+Shift+I
 - Configurable to block specific shortcuts
 - Provides custom event handlers for blocked shortcuts
 
 
-### 2. Context Menu Protection (ContextMenuStrategy)
+### 2. Clipboard Protection (ClipboardStrategy)
+
+**Purpose**: Intercepts clipboard operations to prevent programmatic copying or tampering via clipboard events.
+
+**Implementation Details**:
+
+- Listens to `copy`, `cut` and `paste` events
+- Can clear or override clipboard data or present a custom handler
+- Useful in combination with selection and context menu protections
+
 
-**Purpose**: Prevents users from accessing the browser's context menu (right-click menu) to copy content or view page source.
+### 3. Context Menu Protection (ContextMenuStrategy)
+
+**Purpose**: Prevents users from accessing the browser's context menu (right-click menu) to copy content, save assets, or inspect elements.
 
 **Implementation Details**:
 
-- Intercepts the contextmenu event on specified elements
+- Intercepts the `contextmenu` event on specified elements
 - Can be applied to the entire document or specific elements
-- Supports custom handler for context menu attempts
+- Supports custom handler for right-click attempts
 
 
-### 3. Print Protection (PrintStrategy)
+### 4. Print Protection (PrintStrategy)
 
-**Purpose**: Prevents users from printing the page or using the browser's print functionality.
+**Purpose**: Prevents or modifies the browser's print behavior to protect content (optionally watermark on print).
 
 **Implementation Details**:
 
-- Intercepts print events (window.print, Ctrl+P)
-- Optionally displays a custom message when print is attempted
-- Can be configured to allow printing but with watermarks
+- Intercepts `window.print` and print keyboard shortcuts
+- Optionally adds a print-only watermark or blocks printing
+- Provides hooks for custom messaging when print is attempted
 
 
-### 4. Selection Protection (SelectionStrategy)
+### 5. Selection Protection (SelectionStrategy)
 
 **Purpose**: Prevents users from selecting and copying text content.
 
 **Implementation Details**:
 
 - Disables text selection via CSS and JavaScript
-- Intercepts selection events
-- Can be applied to specific elements or the entire document
-- Supports custom handler for selection attempts
+- Intercepts selection events and clears selection ranges
+- Can be applied selectively to elements or site-wide
 
 
-### 5. Watermark Protection (WatermarkStrategy)
+### 6. Watermark Protection (WatermarkStrategy)
 
 **Purpose**: Adds visible watermarks to the content to discourage unauthorized sharing and identify the source.
 
@@ -91,30 +226,51 @@ This architecture allows for flexible configuration and easy extension with new
 - Supports customization of text, opacity, density, and positioning
 - Includes user identification (userId) to trace leaked content
 - **Observer Mechanism**: Implements a MutationObserver to detect when watermarks are removed from the DOM and automatically regenerates them
-- Watermarks are positioned in a way that makes them difficult to remove without affecting the content
 
 
-### 6. DevTools Protection (DevToolsStrategy)
+### 7. DevTools Protection (DevToolsStrategy)
 
 **Purpose**: Detects and responds to attempts to open browser developer tools, which could be used to inspect and modify the page.
 
 **Implementation Details**:
 
-- Uses multiple detection techniques (window.devtools, console timing, resize detection)
+- Uses multiple detection techniques (console timing, resize detection, feature checks)
 - Provides callbacks when DevTools are opened or closed
-- Can be configured to take specific actions when DevTools are detected
+- Can be configured to take specific actions (log, blur, overlay) when DevTools are detected
 
 
-### 7. Screenshot Protection (ScreenshotStrategy)
+### 8. Screenshot Protection (ScreenshotStrategy)
 
 **Purpose**: Detects and responds to screenshot attempts.
 
 **Implementation Details**:
 
-- Monitors clipboard events and screen capture APIs
-- Blurs content or displays warning message during screenshot attempts
+- Monitors clipboard events and screen capture API usage
+- Blurs content or displays a warning message during screenshot attempts
 - Provides callbacks when screenshot attempts are detected
-- Uses visual tricks to make screenshots less useful (temporary content blurring)
+- Uses visual techniques to make screenshots less useful (temporary content blurring)
+
+
+### 9. Extension Detection (BrowserExtensionDetectionStrategy)
+
+**Purpose**: Detects suspicious or known browser extensions that may bypass protections.
+
+**Implementation Details**:
+
+- Heuristics and detection strategies to identify extensions
+- Callbacks for detected extensions
+- Optionally disable protections or report detections to a backend
+
+
+### 10. Frame Embedding Protection (FrameEmbeddingProtectionStrategy)
+
+**Purpose**: Detects and prevents the page from being embedded into unauthorized frames.
+
+**Implementation Details**:
+
+- Checks `top`/`window` relationships and hostnames
+- Optionally break out of frames or display a blocking overlay
+- Configurable whitelist of allowed origins
 
 
 ## Technical Deep Dive
@@ -145,16 +301,27 @@ The screenshot protection uses several techniques to detect and respond to scree
 
 ## Known Limitations and Issues
 
-While Content Security Toolkit provides robust protection, it's important to understand its limitations:
+While Content Security Toolkit provides robust protection, it's important to understand its limitations and where protections are best applied.
+
+### Browser compatibility & limitations
+
+| Feature | Desktop | Mobile | Notes |
+|---|---:|---:|---|
+| DevTools detection | Good on modern Chromium & Firefox | Limited | Mobile devices have limited toolsets; detection techniques may be unreliable.
+| Screenshot detection | Partial | Partial | Can detect some screen-capture APIs and clipboard activity; cannot prevent OS-level screenshots or photos.
+| Watermarking | Good | Good | MutationObserver + DOM-based watermarks work on modern browsers; heavy density may impact layout and perf.
+| Extension detection | Limited | N/A | Heuristic-based; may produce false positives and won't detect all malicious extensions.
+| Frame embedding protection | Good | Good | Works when combined with proper server headers (CSP/X-Frame-Options) for stronger enforcement.
+
+> Notes: Protections operate in the browser and are best used as a **deterrent** and part of defense-in-depth. They are not a substitute for server-side access control or legal protections.
+
+### Other important limitations
 
-1. **Client-Side Only**: As a JavaScript library, all protections run in the browser and can potentially be circumvented by determined users with technical knowledge.
-2. **No Server-Side Validation**: The library doesn't include server-side components to validate content access or enforce permissions beyond the browser.
-3. **Browser Compatibility**: Some protection strategies rely on modern browser APIs and may not work in older browsers.
-4. **Mobile Limitations**: Some protections (particularly DevTools detection) are less effective on mobile devices.
-5. **Accessibility Impact**: Content protection measures can interfere with accessibility tools. Care should be taken to ensure content remains accessible to users with disabilities.
-6. **Performance Considerations**: Extensive protection, particularly watermarking with high density, can impact page performance.
-7. **Hardware Screenshots**: The library cannot prevent screenshots taken using physical cameras or external hardware.
-8. **Browser Extensions**: Some browser extensions might interfere with or bypass certain protection mechanisms.
+- **Client-Side Only**: All protections run in the browser and can potentially be bypassed by determined attackers.
+- **Accessibility Impact**: Some protections can affect accessibility tools; test and provide alternative access for users who need it.
+- **Performance Considerations**: High-density watermarks or many simultaneous observers may impact rendering performance on low-end devices.
+- **Hardware Screenshots**: Cannot prevent photos taken with external cameras or devices.
+- **Browser Extensions**: Extensions may interfere with or bypass protections; treat extension detection as heuristic rather than absolute.
 
 Unlike DRM systems that encrypt content and control playback through specialized software, Content Security Toolkit focuses on preventing common extraction methods while maintaining compatibility with standard web browsers. It's designed as a deterrent rather than an unbreakable protection system.
 
@@ -168,4 +335,21 @@ For optimal protection, consider these implementation guidelines:
 4. **Selective Protection**: Apply protection only to sensitive content to minimize performance impact
 5. **Regular Updates**: Keep the library updated to benefit from security improvements
 6. **Complementary Measures**: Combine with server-side protections and legal terms of use
-7. **Accessibility Considerations**: Test with accessibility tools and provide alternative access methods for legitimate users with special needs
+7. **Accessibility Considerations**: Test with accessibility tools and provide alternative access methods for legitimate users with special needs
+
+## Contributing
+
+Contributions are welcome! To contribute:
+
+- Fork the repository and create a feature branch from `main`.
+- Run `npm install`, `npm run lint`, `npm test`, and `npm run build` locally before pushing.
+- Open a clear pull request explaining the change and link any relevant issues.
+- Add tests for new behavior and update the README/examples when adding features.
+
+Please be respectful and follow the project's Code of Conduct (see below).
+
+## Code of Conduct
+
+This project follows the Contributor Covenant. By participating you agree to the terms in `CODE_OF_CONDUCT.md`.
+
+---

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "content-security-toolkit",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "type": "module",
   "types": "dist/index.d.ts",
@@ -19,12 +19,19 @@
     "examples:start": "cd examples && npm run start"
   },
   "keywords": [
-    "security",
+    "content-security",
     "content-protection",
-    "drm",
-    "web-security"
+    "web-security",
+    "anti-screenshot",
+    "devtools-detection",
+    "watermark",
+    "copy-protection",
+    "browser-security",
+    "typescript",
+    "javascript",
+    "frontend-security"
   ],
-  "author": "Iker Laforga",
+  "author": "Isonimus",
   "license": "MIT",
   "repository": {
     "type": "git",