dphelper 3.7.1 → 3.7.2

package/docs/markdown/sanitize.md

@@ -0,0 +1,118 @@
+# sanitize
+
+Input/output sanitization for security.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `html` | Sanitize HTML by escaping special characters | `dphelper.sanitize.html(html)` |
+
+## Description
+
+Security-focused sanitization utilities:
+- **HTML Escape** - Convert special characters to HTML entities
+- **XSS Prevention** - Prevent cross-site scripting attacks
+- **Input Validation** - Clean user-provided content
+
+## Usage Examples
+
+### HTML Sanitization
+
+```javascript
+// Escape HTML special characters
+const userInput = '<script>alert("XSS")</script>';
+const safe = dphelper.sanitize.html(userInput);
+// Output: "<script>alert("XSS")</script>"
+
+// More examples
+const html1 = dphelper.sanitize.html('<div class="test">Hello</div>');
+// "<div class="test">Hello</div>"
+
+const html2 = dphelper.sanitize.html('Use <br> for line breaks');
+// "Use <br> for line breaks"
+
+const html3 = dphelper.sanitize.html("It's a beautiful day");
+// "It's a beautiful day"
+```
+
+### Display User Content Safely
+
+```javascript
+// Safely display user comments
+function displayComment(comment) {
+  const sanitized = dphelper.sanitize.html(comment);
+  document.getElementById('comments').innerHTML = sanitized;
+}
+
+// User input (malicious)
+const maliciousInput = '<img src=x onerror=alert(1)>';
+displayComment(maliciousInput);
+// Safely displays as text, not executed
+
+// Chat message sanitization
+const messages = [
+  '<b>User1:</b> Hello everyone!',
+  '<script>stealCookies()</script>Welcome!',
+  'Check out <a href="http://evil.com">this link</a>'
+];
+
+messages.forEach(msg => {
+  console.log(dphelper.sanitize.html(msg));
+});
+// <b>User1:</b> Hello everyone!
+// <script>stealCookies()</script>Welcome!
+// Check out <a href="http://evil.com">this link</a>
+```
+
+### Form Input Validation
+
+```javascript
+// Sanitize form inputs before storage
+function sanitizeFormInput(input) {
+  if (typeof input !== 'string') return '';
+  return dphelper.sanitize.html(input.trim());
+}
+
+const formData = {
+  username: '  <script>bad()</script>user  ',
+  bio: 'I love <programming> and "quotes"',
+  website: 'https://example.com'
+};
+
+const sanitized = {
+  username: sanitizeFormInput(formData.username),
+  bio: sanitizeFormInput(formData.bio),
+  website: sanitizeFormInput(formData.website)
+};
+// { username: "<script>bad()</script>user", ... }
+```
+
+### Database Storage
+
+```javascript
+// Sanitize before storing in database
+function saveToDatabase(data) {
+  const sanitized = {};
+  for (const key in data) {
+    if (typeof data[key] === 'string') {
+      sanitized[key] = dphelper.sanitize.html(data[key]);
+    } else {
+      sanitized[key] = data[key];
+    }
+  }
+  return sanitized;
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20241204
+- **Last Modified:** 20241204
+- **Environment:** both (browser + Node.js)
+
+---
+
+*Automatically generated document*

package/docs/markdown/screen.md

@@ -0,0 +1,78 @@
+# screen
+
+Functionality for screen and fullscreen management.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `fullScreen` | Enter fullscreen mode | `dphelper.screen.fullScreen(element)` |
+| `toggle` | Toggle fullscreen mode | `dphelper.screen.toggle(element)` |
+
+## Description
+
+Browser fullscreen control:
+- **Fullscreen** - Request fullscreen for any element
+- **Toggle** - Switch between fullscreen and normal mode
+- **Video** - Perfect for video players and presentations
+
+## Usage Examples
+
+### Enter Fullscreen
+
+```javascript
+// Fullscreen entire page
+dphelper.screen.fullScreen();
+
+// Fullscreen specific element
+const video = document.getElementById('myVideo');
+dphelper.screen.fullScreen(video);
+
+// Fullscreen modal
+const modal = document.getElementById('modal');
+dphelper.screen.fullScreen(modal);
+```
+
+### Toggle Fullscreen
+
+```javascript
+// Toggle on/off
+dphelper.screen.toggle();
+
+// Toggle specific element
+const element = document.getElementById('container');
+dphelper.screen.toggle(element);
+```
+
+### Video Player Fullscreen
+
+```javascript
+// Fullscreen video player
+const videoPlayer = document.getElementById('video-player');
+const fullscreenBtn = document.getElementById('fullscreen-btn');
+
+fullscreenBtn.addEventListener('click', () => {
+  dphelper.screen.toggle(videoPlayer);
+});
+
+// Handle fullscreen change
+document.addEventListener('fullscreenchange', () => {
+  if (document.fullscreenElement) {
+    console.log('Entered fullscreen');
+  } else {
+    console.log('Exited fullscreen');
+  }
+});
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20240101
+- **Last Modified:** 20240101
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/scrollbar.md

@@ -0,0 +1,82 @@
+# scrollbar
+
+Scrollbar customization and scrolling utilities.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `custom` | Apply custom scrollbar styles | `dphelper.scrollbar.custom('.container')` |
+| `indicator` | Add scroll progress indicator | `dphelper.scrollbar.indicator({ el: '#content' })` |
+| `position.get` | Get saved scroll position | `dphelper.scrollbar.position.get('#container')` |
+| `position.set` | Save scroll position | `dphelper.scrollbar.position.set('#container')` |
+| `smooth` | Smooth mouse wheel scrolling | `dphelper.scrollbar.smooth(target, speed, smooth)` |
+| `scrollTo` | Scroll to element | `dphelper.scrollbar.scrollTo('#container', '#element', 20)` |
+
+## Description
+
+Scrollbar management:
+- **Custom Styling** - Apply custom scrollbar CSS
+- **Progress Indicator** - Show scroll progress bar
+- **Position Memory** - Save/restore scroll position
+- **Smooth Scrolling** - Custom smooth scroll behavior
+
+## Usage Examples
+
+### Custom Scrollbar
+
+```javascript
+// Apply custom scrollbar styles
+dphelper.scrollbar.custom('.scroll-container', {
+  color_1: '#888',
+  color_1_hover: '#555',
+  width: '12px',
+  height: '12px',
+  rounded: '6px'
+});
+```
+
+### Scroll Indicator
+
+```javascript
+// Add scroll progress indicator
+dphelper.scrollbar.indicator({
+  el: '#main-content'
+});
+
+// Adds progress bar at top of page
+```
+
+### Scroll Position
+
+```javascript
+// Save scroll position
+dphelper.scrollbar.position.set('#chat-container');
+
+// Restore on page load
+dphelper.scrollbar.position.get('#chat-container');
+
+// Useful for chat apps, long content
+```
+
+### Scroll To Element
+
+```javascript
+// Scroll to element with gap
+dphelper.scrollbar.scrollTo('#container', '#target-section', 50);
+
+// Smooth scroll to section
+dphelper.scrollbar.scrollTo('body', '#footer');
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Client-side only (browser)
+
+---
+
+*Automatically generated document*

package/docs/markdown/security.md

@@ -0,0 +1,289 @@
+# security
+
+Comprehensive security and cryptography utilities for encryption, hashing, identity generation, and browser fingerprinting.
+
+## Functions
+
+### UUID Generation
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `uuid.v4` | Generates a random UUID v4 | `dphelper.security.uuid.v4` |
+| `uuid.v5` | Generates a random UUID v5 | `dphelper.security.uuid.v5` |
+| `uuid.byVal` | Generates a deterministic UUID from a string | `dphelper.security.uuid.byVal('string')` |
+
+### Encryption/Decryption
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `crypt` | Encrypts data using AES-256-GCM | `await dphelper.security.crypt(data, secret)` |
+| `deCrypt` | Decrypts AES-256-GCM encrypted data | `await dphelper.security.deCrypt(encrypted, secret)` |
+| `AES_KeyGen` | Generates a secure AES key | `await dphelper.security.AES_KeyGen(passKey)` |
+
+### Hashing
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `hashPass` | Creates secure password hash with salt (SHA-256) | `await dphelper.security.hashPass(user, pass)` |
+| `SHA256_Hex` | Generates SHA-256 hash in hexadecimal | `await dphelper.security.SHA256_Hex(data)` |
+
+### Identity Generation
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `ulid` | Generates Universally Unique Lexicographically Sortable Identifier | `dphelper.security.ulid()` |
+| `fingerprint` | Generates unique browser fingerprint | `await dphelper.security.fingerprint()` |
+
+### Secure Storage
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `saveEncrypted` | Encrypts and saves data to localStorage with HMAC | `await dphelper.security.saveEncrypted(key, value, secret)` |
+| `getEncrypted` | Retrieves and decrypts data from localStorage | `await dphelper.security.getEncrypted(key, secret)` |
+
+## Description
+
+Enterprise-grade security module providing:
+- **UUID Generation** - v4 (random), v5 (namespace-based), deterministic
+- **Encryption** - AES-256-GCM with PBKDF2 key derivation
+- **Hashing** - SHA-256 with secure salt generation
+- **Identity** - ULID for sortable unique IDs, browser fingerprinting
+- **Secure Storage** - Encrypted localStorage with HMAC integrity
+
+## Usage Examples
+
+### UUID Generation
+
+```javascript
+// Random UUID v4 (most common use case)
+console.log(dphelper.security.uuid.v4);
+// "550e8400-e29b-41d4-a716-446655440000"
+
+// Random UUID v5
+console.log(dphelper.security.uuid.v5);
+// "a3bb189e-8bf9-3888-9912-ace4e6543002"
+
+// Deterministic UUID from string (same input = same output)
+console.log(dphelper.security.uuid.byVal('hello'));
+// "2cfb4a2e-7b3c-4a8e-9d1c-5e4f6a7b8c9d"
+
+console.log(dphelper.security.uuid.byVal('hello'));
+// "2cfb4a2e-7b3c-4a8e-9d1c-5e4f6a7b8c9d" (same!)
+
+// Useful for generating consistent IDs from usernames
+const userId = dphelper.security.uuid.byVal('john@example.com');
+```
+
+### Encryption/Decryption
+
+```javascript
+// Encrypt sensitive data
+const secret = 'my-secret-password';
+const data = 'Hello, World!';
+
+const encrypted = await dphelper.security.crypt(data, secret);
+console.log(encrypted);
+// "base64encodedstring..." (contains salt + iv + encrypted data)
+
+// Decrypt the data
+const decrypted = await dphelper.security.deCrypt(encrypted, secret);
+console.log(decrypted); // "Hello, World!"
+
+// Generate a secure key from password
+const key = await dphelper.security.AES_KeyGen('user-password');
+console.log(key);
+// "salthadexstring...keybits..."
+```
+
+### Password Hashing
+
+```javascript
+// Hash a password (with automatic salt generation)
+const user = 'john@example.com';
+const password = 'mySecurePassword!123';
+
+const hash = await dphelper.security.hashPass(user, password);
+console.log(hash);
+// "salthere...hashhere..." (64 char hex string)
+
+// Verify password later
+const storedHash = '...'; // Previously stored hash
+const inputPassword = 'mySecurePassword!123';
+const newHash = await dphelper.security.hashPass(user, inputPassword);
+
+if (newHash === storedHash) {
+  console.log('Password correct!');
+} else {
+  console.log('Invalid password');
+}
+
+// SHA-256 hash (raw)
+const sha256 = await dphelper.security.SHA256_Hex('hello world');
+console.log(sha256);
+// "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+```
+
+### ULID Generation
+
+```javascript
+// Generate ULID (unique, lexicographically sortable, time-based)
+const id1 = dphelper.security.ulid();
+const id2 = dphelper.security.ulid();
+
+console.log(id1); // "01ARYZ6S41TVGZFM0X5SZW0JYP"
+console.log(id2); // "01ARYZ6S41TVHZ0WS0QJZWMY5A"
+
+// ULIDs are time-sortable
+console.log(id1 < id2); // true (if id1 was created first)
+
+// Great for database primary keys
+const orderId = dphelper.security.ulid(); // Sortable by creation time
+```
+
+### Browser Fingerprinting
+
+```javascript
+// Generate unique browser fingerprint
+const fingerprint = await dphelper.security.fingerprint();
+console.log(fingerprint);
+// "a1b2c3d4e5f6..." (SHA-256 hash)
+
+// Use for analytics, fraud detection, or session management
+async function identifyUser() {
+  const fp = await dphelper.security.fingerprint();
+
+  // Send to your server
+  await fetch('/api/identify', {
+    method: 'POST',
+    body: JSON.stringify({ fingerprint: fp })
+  });
+}
+```
+
+### Secure LocalStorage
+
+```javascript
+// Save encrypted data to localStorage
+await dphelper.security.saveEncrypted('user_token', 'abc123xyz', 'my-secret');
+
+await dphelper.security.saveEncrypted('user_data', JSON.stringify({
+  name: 'John',
+  email: 'john@example.com'
+}), 'my-secret');
+
+// Retrieve and decrypt data
+const token = await dphelper.security.getEncrypted('user_token', 'my-secret');
+console.log(token); // "abc123xyz"
+
+const userData = await dphelper.security.getEncrypted('user_data', 'my-secret');
+console.log(JSON.parse(userData));
+// { name: 'John', email: 'john@example.com' }
+
+// Tamper detection - returns null if data was modified
+localStorage.setItem('user_token', 'modified_by_hacker');
+const tampered = await dphelper.security.getEncrypted('user_token', 'my-secret');
+console.log(tampered); // null (detected tampering!)
+```
+
+## Security Features
+
+### AES-256-GCM Encryption
+- Uses PBKDF2 with **310,000 iterations** (OWASP 2023 compliant) for key derivation
+- Random 16-byte salt for each encryption
+- Random 12-byte IV (Initialization Vector)
+- Authenticated encryption (confidentiality + integrity)
+
+### Secure Password Hashing
+- **SHA-256 only** (CNSA compliant, SHA-1 deprecated)
+- Random 16-byte salt per hash
+- Salt + hash stored together for verification
+- Time-safe comparison
+
+### HMAC-Protected Storage
+- AES encryption for confidentiality
+- HMAC-SHA256 for integrity verification
+- Tamper detection on retrieval
+- Version support for future updates
+
+### Network Functions Security
+
+> [!IMPORTANT]
+> Network primitives (`fetch`, `sse`, `socket`) are **by design** for modern web development. Callers must:
+> - Validate and sanitize all URLs before passing to these functions
+> - Use `dphelper.sanitize.url()` for URL validation
+> - Never pass untrusted user input directly to network functions
+
+```javascript
+// Correct usage
+const safeUrl = dphelper.sanitize.url(userInput);
+await dphelper.fetch.get(safeUrl);
+```
+
+## Advanced Usage
+
+### Complete Authentication Flow
+
+```javascript
+class AuthManager {
+  constructor(secret) {
+    this.secret = secret;
+  }
+
+  async register(username, password) {
+    // Hash password for storage
+    const hash = await dphelper.security.hashPass(username, password);
+
+    // Generate user ID
+    const userId = dphelper.security.uuid.byVal(username);
+
+    // Save user data securely
+    await dphelper.security.saveEncrypted(`user_${userId}`,
+      JSON.stringify({ hash, created: Date.now() }),
+      this.secret
+    );
+
+    return userId;
+  }
+
+  async login(username, password) {
+    const userId = dphelper.security.uuid.byVal(username);
+    const stored = await dphelper.security.getEncrypted(`user_${userId}`, this.secret);
+
+    if (!stored) return null;
+
+    const userData = JSON.parse(stored);
+    const inputHash = await dphelper.security.hashPass(username, password);
+
+    return inputHash === userData.hash ? userId : null;
+  }
+}
+```
+
+### Secure Message Passing
+
+```javascript
+async function sendSecureMessage(recipient, message) {
+  // Generate encryption key
+  const key = await dphelper.security.AES_KeyGen(recipient);
+
+  // Encrypt message
+  const encrypted = await dphelper.security.crypt(message, key);
+
+  // Create message ID
+  const messageId = dphelper.security.ulid();
+
+  return { id: messageId, encrypted, key };
+}
+```
+
+## Details
+
+- **Author:** Dario Passariello & Jo
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** Works in both client and server environments
+
+---
+
+*Automatically generated document*

package/docs/markdown/shortcut.md

@@ -0,0 +1,100 @@
+# shortcut
+
+Keyboard shortcut management.
+
+## Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `keys` | Handle keyboard shortcuts | `dphelper.shortcut.keys(event, trigger)` |
+
+## Description
+
+Keyboard shortcut system:
+- **Custom Shortcuts** - Define your own keyboard shortcuts
+- **Ctrl/Meta Keys** - Support for modifier keys
+- **Element Actions** - Trigger clicks on elements
+- **Function Callbacks** - Execute custom functions
+
+## Usage Examples
+
+### Basic Shortcut Handling
+
+```javascript
+// Handle keyboard events
+document.addEventListener('keydown', (e) => {
+  dphelper.shortcut.keys(e);
+});
+```
+
+### Custom Shortcut Configuration
+
+```javascript
+// Define custom shortcuts
+const shortcuts = {
+  data: [
+    {
+      key: '83',        // S key
+      ctrl: true,       // requires Ctrl
+      active: true,
+      description: 'Save - CTRL+S',
+      element: '#save-btn',
+      function: ''
+    },
+    {
+      key: '80',        // P key
+      ctrl: true,
+      active: true,
+      description: 'Print - CTRL+P',
+      element: '',
+      function: 'print()'
+    },
+    {
+      key: '27',        // ESC
+      ctrl: false,
+      active: true,
+      description: 'Close - ESC',
+      element: '#close-modal',
+      function: ''
+    }
+  ]
+};
+
+document.addEventListener('keydown', (e) => {
+  dphelper.shortcut.keys(e, shortcuts);
+});
+```
+
+### Save Form
+
+```javascript
+// Auto-save with Ctrl+S
+const formShortcuts = {
+  data: [
+    {
+      key: '83',
+      ctrl: true,
+      active: true,
+      description: 'Save form',
+      element: '#save-form-btn',
+      function: ''
+    }
+  ]
+};
+
+document.addEventListener('keydown', (e) => {
+  dphelper.shortcut.keys(e, formShortcuts);
+});
+```
+
+## Details
+
+- **Author:** Dario Passariello
+- **Version:** 0.0.2
+- **Creation Date:** 20210101
+- **Last Modified:** 20260220
+- **Environment:** client (browser)
+
+---
+
+*Automatically generated document*