ng2-pdfjs-viewer 25.0.9 → 25.0.10

package/README.md

@@ -57,6 +57,7 @@ Whether you need a simple embedded PDF viewer or a complex document management s
 | **Enhanced Error Handling**   | Multiple error display styles with custom templates                | ✅ New |
 | **Mobile-First Design**       | Responsive layout optimized for touch devices                      | ✅ New |
 | **TypeScript Strict Mode**    | Full type safety with comprehensive API coverage                   | ✅ New |
+| **URL Security Validation**   | Prevents unauthorized file parameter manipulation with custom templates | ✅ New |
 
 ### 🏆 Unique Advantages
 
@@ -197,6 +198,13 @@ Add PDF.js assets to your `angular.json`:
 - **🔄 Rotation & Zoom** - Document manipulation with smooth animations
 - **📱 Touch Gestures** - Mobile-optimized touch interactions
 
+### 🔒 Security Features
+
+- **CSP Compliant** - Works with strict Content Security Policy (`style-src 'self'`)
+- **URL Validation** - Prevents unauthorized file parameter manipulation in external viewer
+- **Custom Security Templates** - Angular template support for security warnings
+- **Console Warnings** - Developer-friendly security notifications
+
 ---
 
 ## 📦 Installation
@@ -207,6 +215,21 @@ Add PDF.js assets to your `angular.json`:
 - **Node.js**: 18.0+
 - **TypeScript**: 5.0+
 
+### Production Deployment
+
+#### Nginx Configuration
+
+For production deployments using nginx, you may need to configure MIME types for PDF.js ES modules (`.mjs` files):
+
+```nginx
+# Add to your nginx.conf or site configuration
+types {
+    application/javascript  js mjs;
+}
+```
+
+**Why this is needed**: PDF.js v5+ uses `.mjs` files (ES modules). Without proper MIME type configuration, nginx serves these files with incorrect content-type headers, causing the PDF viewer to crash during loading in production environments.
+
 ### Angular Version Support
 
 | Angular Version | Support Level | Notes |
@@ -284,6 +307,31 @@ Add PDF.js assets to your `angular.json`:
 </ng2-pdfjs-viewer>
 ```
 
+### Security Configuration
+
+```html
+<!-- Basic security (default enabled) -->
+<ng2-pdfjs-viewer 
+  pdfSrc="assets/document.pdf"
+  [urlValidation]="true">
+</ng2-pdfjs-viewer>
+
+<!-- Custom security template -->
+<ng2-pdfjs-viewer 
+  pdfSrc="assets/document.pdf"
+  [urlValidation]="true"
+  [customSecurityTpl]="securityTemplate">
+</ng2-pdfjs-viewer>
+
+<ng-template #securityTemplate let-warning="securityWarning">
+  <div class="alert alert-warning" *ngIf="warning">
+    <h4>⚠️ Security Warning</h4>
+    <p>{{ warning.message }}</p>
+    <button (click)="pdfViewer.dismissSecurityWarning()">Dismiss</button>
+  </div>
+</ng-template>
+```
+
 ### Programmatic Control
 
 ```typescript
@@ -364,6 +412,84 @@ export class MyComponent {
 </ng2-pdfjs-viewer>
 ```
 
+### External Window Behavior
+
+```html
+<!-- Basic external window (reuses same tab) -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf"
+  [externalWindow]="true">
+</ng2-pdfjs-viewer>
+
+<!-- Custom window options -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf"
+  [externalWindow]="true"
+  [externalWindowOptions]="'width=1200,height=800,scrollbars=yes,resizable=yes'">
+</ng2-pdfjs-viewer>
+
+<!-- Force new tab each time -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf"
+  [externalWindow]="true"
+  [target]="'pdf-viewer-' + Date.now()">
+</ng2-pdfjs-viewer>
+```
+
+**Tab Reuse Behavior:**
+- **Same `target` name** → Reuses existing tab (default behavior)
+- **Unique `target` name** → Always opens new tab
+- **`target="_blank"`** → Browser decides (usually reuses)
+
+### iframe Security
+
+```html
+<!-- Built-in security (always enabled) -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf">
+</ng2-pdfjs-viewer>
+```
+
+**Built-in Security Features:**
+- **Static Sandbox** - `allow-forms allow-scripts allow-same-origin allow-modals`
+- **XSS Prevention** - Prevents malicious scripts from affecting parent page
+- **CSP Compliance** - Meets Content Security Policy requirements
+- **Data Protection** - Limits iframe access to parent window context
+- **Enterprise Ready** - Suitable for corporate security environments
+
+**Sandbox Attributes (Fixed for Security):**
+- `allow-forms` - Required for PDF form functionality
+- `allow-scripts` - Required for PDF.js JavaScript execution
+- `allow-same-origin` - Required for loading PDF files and assets
+- `allow-modals` - Required for PDF.js dialogs (print, download)
+
+### iframe Styling
+
+```html
+<!-- Default (no border) -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf">
+</ng2-pdfjs-viewer>
+
+<!-- Custom border -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf"
+  iframeBorder="2px solid #ccc">
+</ng2-pdfjs-viewer>
+
+<!-- Numeric border -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf"
+  [iframeBorder]="1">
+</ng2-pdfjs-viewer>
+
+<!-- No border (explicit) -->
+<ng2-pdfjs-viewer 
+  pdfSrc="document.pdf"
+  iframeBorder="0">
+</ng2-pdfjs-viewer>
+```
+
 ---
 
 ## 📚 API Reference
@@ -376,8 +502,8 @@ export class MyComponent {
 | `viewerId`                   | `string`                                  | auto         | Unique viewer identifier              |
 | `viewerFolder`               | `string`                                  | `'assets'`   | Path to PDF.js assets                 |
 | `externalWindow`             | `boolean`                                 | `false`      | Open in new window                    |
-| `externalWindowOptions`      | `string`                                  | -            | External window options               |
-| `target`                     | `string`                                  | `'_blank'`   | Target for external window            |
+| `externalWindowOptions`      | `string`                                  | -            | External window options (size, position, etc.) |
+| `target`                     | `string`                                  | `'_blank'`   | Target for external window (controls tab reuse) |
 | `theme`                      | `'light' \| 'dark' \| 'auto'`             | `'light'`    | Theme selection                       |
 | `primaryColor`               | `string`                                  | `'#007acc'`  | Primary color for UI elements         |
 | `backgroundColor`            | `string`                                  | `'#ffffff'`  | Background color                      |
@@ -386,6 +512,8 @@ export class MyComponent {
 | `textColor`                  | `string`                                  | -            | Text color                            |
 | `borderRadius`               | `string`                                  | -            | Border radius                         |
 | `customCSS`                  | `string`                                  | -            | Custom CSS styles                     |
+| `cspNonce`                   | `string`                                  | -            | CSP nonce for customCSS (optional)    |
+| `iframeTitle`                | `string`                                  | -            | Accessible title for iframe (optional) |
 | `showSpinner`                | `boolean`                                 | `true`       | Show loading spinner                  |
 | `customSpinnerTpl`           | `TemplateRef`                             | -            | Custom spinner template               |
 | `spinnerClass`               | `string`                                  | -            | Custom spinner CSS class              |
@@ -437,6 +565,10 @@ export class MyComponent {
 | `themeConfig`                | `ThemeConfig`                             | -            | Theme configuration                   |
 | `groupVisibility`            | `GroupVisibilityConfig`                   | -            | Group visibility configuration        |
 | `layoutConfig`               | `LayoutConfig`                            | -            | Layout configuration                  |
+| `urlValidation`              | `boolean`                                 | `true`       | Enable URL validation                 |
+| `customSecurityTpl`          | `TemplateRef<any>`                        | -            | Custom security template              |
+| `securityWarning`            | `SecurityWarning \| null`                 | -            | Security warning data (read-only)     |
+| `iframeBorder`               | `string \| number`                        | `"0"`        | iframe border style                   |
 
 ### Output Events
 
@@ -491,6 +623,8 @@ export class MyComponent {
 | `goBack()`                                               | -                                                           | `void`                                               | Go back in browser history        |
 | `closeViewer()`                                          | -                                                           | `void`                                               | Close viewer window               |
 | `getErrorTemplateData()`                                 | -                                                           | `any`                                                | Get error template data           |
+| `setUrlValidation(enabled: boolean)`                     | `enabled: boolean`                                          | `Promise<ActionExecutionResult>`                     | Enable/disable URL validation     |
+| `dismissSecurityWarning()`                               | -                                                           | `void`                                               | Dismiss security warning          |
 
 ---
 
@@ -782,7 +916,7 @@ This project is licensed under the **Apache License 2.0 + Commons Clause License
 - 💬 **Community**: [GitHub Discussions](https://github.com/intbot/ng2-pdfjs-viewer/discussions)
 - 🐛 **Issues**: [GitHub Issues](https://github.com/intbot/ng2-pdfjs-viewer/issues)
 - 📧 **Email**: codehippie1@gmail.com
-- 📧 **Author**: [Aneesh Gopalakrishnan](http://github.com/codehippie1)
+- 👨‍💻 **Author**: [Aneesh Gopalakrishnan](http://github.com/codehippie1)
 
 ---