web-shield.js/README.md

Content security library to prevent downloading videos, copying text, and saving images

# web-shield.js

A lightweight JavaScript library to protect web content from unauthorized copying, downloading, or saving.

> **⚠️ WARNING: BETA SOFTWARE**  
> This library is still under active development and is considered BETA software. It may contain bugs, incomplete features, or undergo significant changes. Use in production environments at your own risk. The developers are not responsible for any data loss, security issues, or other damages that may result from using this library. Always thoroughly test in a staging environment before deploying.

## Features

- **Video Protection**: Prevent video downloads and right-click actions.
- **Text Protection**: Block text selection and copying.
- **Image Protection**: Prevent image downloads, right-clicks, and add watermarks.
- **Selective Targeting**: Apply protections only to specific elements using CSS selectors.
- **Dynamic Content Support**: Automatically protect new content added to the page after initialization.
- **Error Resilience**: Built-in error handling prevents crashes when operating in challenging environments.

## Installation

### Using npm or yarn

```bash
npm install web-shield.js
# or
yarn add web-shield.js
```

### Direct Browser Usage via CDN

Add the script directly to your HTML:

```html
<!-- Use a specific version -->
<script src="https://cdn.jsdelivr.net/npm/web-shield.js@0.1.5/dist/index.js"></script>

<!-- Or always use the latest version (not recommended for production) -->
<script src="https://cdn.jsdelivr.net/npm/web-shield.js/dist/index.js"></script>

<script>
  // The library is available as a global variable named WebShield
  const shield = new WebShield({
    video: true,
    text: true,
    image: true
  });
</script>
```

## Usage

### Basic Usage

```javascript
import WebShield from 'web-shield.js';

// Enable all protections with default settings
const shield = new WebShield({
  video: true,
  text: true,
  image: true
});
```

### Basic Usage with ES Modules

```javascript
// ES Module import
import WebShield from 'web-shield.js';

// Enable all protections with default settings
const shield = new WebShield({
  video: true,
  text: true,
  image: true
});
```

### CommonJS Usage (Node.js)

```javascript
// CommonJS require
const WebShield = require('web-shield.js');

// Enable all protections with default settings
const shield = new WebShield({
  video: true,
  text: true,
  image: true
});
```

### Advanced Configuration

```javascript
import WebShield from 'web-shield.js';

const shield = new WebShield({
  video: {
    preventRightClick: true,
    hideControls: true,
    disableDevTools: true,
    targetSelector: 'video.protected', // Only protect videos with class 'protected'
    observeDynamicContent: true // Protect videos added after initialization
  },
  text: {
    preventSelection: true,
    preventCopy: true,
    preventPrintScreen: true,
    targetSelector: '.content-protected p, article h1', // Protect only specific text elements
    observeDynamicContent: true // Protect new text elements added after initialization
  },
  image: {
    preventRightClick: true,
    preventDrag: true,
    addWatermark: 'Copyright 2025', // or true for default "Protected" text
    targetSelector: '.gallery img', // Only protect images in galleries
    observeDynamicContent: true // Protect images added after initialization
  },
  // Global setting for all shields (can be overridden by individual shields)
  observeDynamicContent: true
});

// Disable all protections when needed
shield.disable();
```

### Individual Shield Usage

You can also use each protection module independently:

```javascript
import { VideoShield, TextShield, ImageShield } from 'web-shield.js';

// Just protect videos
const videoProtection = new VideoShield({
  preventRightClick: true,
  hideControls: true
});

// Just protect text
const textProtection = new TextShield({
  preventSelection: true,
  preventCopy: true
});

// Just protect images
const imageProtection = new ImageShield({
  addWatermark: 'Company Name',
  convertToCanvas: true
});
```

## API Reference

### Global Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `observeDynamicContent` | boolean | `true` | Automatically protect dynamically added content. |

### Options

#### Video Protection

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `preventRightClick` | boolean | `true` | Disables right-click on videos. |
| `hideControls` | boolean | `false` | Hides video controls (play, pause, etc.). |
| `disableDevTools` | boolean | `true` | Makes video sources harder to access through developer tools. |
| `targetSelector` | string | `"video"` | CSS selector to target specific videos. |
| `observeDynamicContent` | boolean | `true` | Protect videos added after initialization. |

#### Text Protection

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `preventSelection` | boolean | `true` | Disables text selection on protected elements. |
| `preventCopy` | boolean | `true` | Blocks copy and cut operations. |
| `preventPrintScreen` | boolean | `false` | Attempts to block print screen actions. |
| `targetSelector` | string | `"p, h1, h2, h3, h4, h5, h6, span, div"` | CSS selector to target specific text elements. |
| `observeDynamicContent` | boolean | `true` | Protect text elements added after initialization. |

#### Image Protection

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `preventRightClick` | boolean | `true` | Disables right-click on images. |
| `preventDrag` | boolean | `true` | Prevents drag-and-drop operations on images. |
| `addWatermark` | boolean/string | `false` | Adds a watermark overlay (custom text or default "Protected"). |
| `targetSelector` | string | `"img"` | CSS selector to target specific images. |
| `observeDynamicContent` | boolean | `true` | Protect images added after initialization. |
| `convertToCanvas` | boolean | `false` | Converts images to canvas elements to prevent URL access. |

### Methods

| Method | Description |
|--------|-------------|
| `disable()` | Disables all active protections. |

## Selective Targeting Examples

Target only premium content:

```javascript
const shield = new WebShield({
  video: {
    targetSelector: '.premium-content video, video[data-protected="true"]',
    preventRightClick: true
  },
  text: {
    targetSelector: '.premium-content p, .premium-content h1',
    preventCopy: true
  },
  image: {
    targetSelector: '.premium-content img',
    addWatermark: 'Premium Content'
  }
});
```

## Dynamic Content Example

Protect content loaded via AJAX or dynamically inserted into the DOM:

```javascript
// Initialize protection
const shield = new WebShield({
  text: {
    targetSelector: '.article-content p',
    observeDynamicContent: true
  },
  image: {
    targetSelector: '.article-content img', 
    observeDynamicContent: true,
    convertToCanvas: true
  }
});

// Later, when new content is added via AJAX
fetch('/api/article/123')
  .then(response => response.json())
  .then(data => {
    const articleDiv = document.createElement('div');
    articleDiv.className = 'article-content';
    articleDiv.innerHTML = data.content; // Contains paragraphs and images
    document.getElementById('content-container').appendChild(articleDiv);
    // web-shield.js automatically protects the new content!
  });
```

## TypeScript Support

web-shield.js includes TypeScript definitions for better development experience:

```typescript
import WebShield, { WebShieldOptions, ImageOptions } from 'web-shield.js';

const imageOptions: ImageOptions = {
  preventRightClick: true,
  addWatermark: 'Copyright',
  convertToCanvas: true
};

const options: WebShieldOptions = {
  image: imageOptions,
  text: true,
  observeDynamicContent: true
};

const shield = new WebShield(options);
```

## Important Notes

- These protections serve as deterrents but are not foolproof. Determined users with technical knowledge can bypass client-side security measures.
- For highly sensitive content, consider additional server-side protections.
- Some protections may affect accessibility; ensure proper testing in your target browsers.
- The library includes cross-browser compatibility for most features.
- Error handling ensures that the library fails gracefully if issues occur.

## Browser Compatibility

web-shield.js is designed to work with modern browsers, including:

- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 80+

## License

MIT License

## Contributing

Contributions are welcome! Feel free to submit a pull request.