@biglogic/rgs 3.9.6 → 3.9.8

package/docs/markdown/security-architecture.md

@@ -0,0 +1,50 @@
+# Security Architecture & Hardening
+
+## Overview
+Reactive Global State (RGS) is designed with a "Security-First" philosophy. Our architecture ensures that global state is not only reactive but protected against common web vulnerabilities and unauthorized access.
+
+## 1. Data Sanitization (XSS Defense)
+The `sanitizeValue` utility provides a robust baseline defense by stripping malicious content from strings and objects before they enter the store.
+
+- **Scheme Blocking**: Specifically blocks `javascript:`, `vbscript:`, and `data:text/html` schemes.
+- **Tag Removal**: Automatically removes dangerous HTML tags such as `<script>`, `<iframe>`, `<form>`, and `<meta>`.
+- **Entity Removal**: Strips HTML entities (`&#...;`) to prevent obfuscation-based bypasses.
+
+## 2. Advanced Deep Cloning
+To ensure state immutability and prevent unintended side effects, RGS uses an intelligent cloning engine:
+- **Native structuredClone**: Leverages the browser's native API for maximum performance.
+- **Support for Collections**: Extends cloning capabilities to `Map` and `Set` objects.
+- **Circular Reference Protection**: Uses `WeakMap` to handle complex nested structures safely.
+
+## 3. Cryptography (AES-256-GCM)
+The security module uses the Web Crypto API to provide high-performance, authenticated encryption:
+- **AES-GCM**: Provides both confidentiality and integrity verification.
+- **GCM (Galois/Counter Mode)**: Ensures that data has not been tampered with during storage.
+- **Safe Random UUID**: Fallback generation for environments without Web Crypto API.
+
+## 4. RBAC (Role-Based Access Control)
+RGS supports fine-grained access rules:
+- **Fail-Closed Design**: Access is denied by default if any rules are defined.
+- **Regex Caching**: Store instances cache compiled regular expressions for ultra-fast permission checks.
+- **ReDoS Protection**: Regex patterns have a 100ms timeout to prevent denial-of-service attacks.
+- **Storage Key Validation**: All persisted keys are validated against a strict pattern before storage.
+
+## 5. Security Best Practices
+For real-world implementations, refer to the `examples/security-best-practices` directory, which covers:
+- **Encryption Key Management**: Using `generateEncryptionKey()` for secure key generation.
+- **Audit Logging**: Tracking all store modifications for compliance.
+- **GDPR Compliance**: Managing user consent and data export/deletion.
+
+## Summary of 2.9.5 Enhancements
+- Robust regex patterns for `sanitizeValue`.
+- Recursive sanitization for plain objects.
+- `Map` and `Set` support in `deepClone`.
+- **Exposed Metadata**: Store instances now expose read-only `namespace` and `userId`.
+- **Direct Store Access**: Added `getStore()` utility for non-React contexts.
+
+## Summary of 3.7.0 Enhancements
+- **ReDoS Protection**: Regex patterns timeout after 100ms to prevent malicious patterns.
+- **Safe UUID**: Fallback UUID generation for environments without Web Crypto API.
+- **Storage Key Validation**: Keys validated before persistence to prevent injection.
+- **Production Safety**: Global window access only enabled in development mode (`NODE_ENV !== 'production'`).
+- **PBKDF2 Key Derivation**: New `deriveKeyFromPassword()` and `generateSalt()` functions for secure password-based encryption (NIST SP 800-132 compliant - 600k iterations, 32-byte salt).

package/docs/markdown/the-magnetar-way.md

@@ -0,0 +1,69 @@
+# 🌌 Chapter 3: The Magnetar Way - Peak Simplicity
+
+If you are a fan of "Clean Code" or just hate writing imports, the **Magnetar** method is your new best friend.
+
+It's a single function that creates the store and the hook simultaneously. **Zero config, 100% typed.**
+
+## 🛠️ The "Master" Example
+
+Let's create a User Profile module.
+
+```typescript
+import { gstate } from '@biglogic/rgs';
+
+// 1. Define the state and create everything in ONE shot
+// Pass a string namespace to enable automatic persistence to localStorage
+export const useUser = gstate({
+  name: 'Guest',
+  isLogged: false,
+  preferences: { theme: 'dark', lang: 'en' }
+}, 'user_module'); // Auto-persists to localStorage (excludes sensitive fields)
+
+// Or use an object config for more control:
+export const useUserNoPersist = gstate({
+  name: 'Guest',
+  isLogged: false
+}, { namespace: 'user_module', autoPersist: false }); // No persistence
+
+// 2. Use it anywhere
+function ProfileHeader() {
+  const [name, setName] = useUser('name');
+  // Note: 'setName' is already typed! It only accepts strings.
+
+  return <h1>Hello, {name}!</h1>;
+}
+```
+
+## 💎 Why Magnetar Rocks
+
+1. **Inferred Types**: No need to define `<string>`. TypeScript looks at the initial value you passed to `gstate` and figures it out.
+2. **Auto-Persistence**: When you pass a string namespace, RGS automatically persists to localStorage (excluding sensitive fields like tokens, passwords, secrets).
+3. **Security**: Sensitive fields (containing 'token', 'password', 'secret', 'key') are automatically excluded from persistence.
+
+```typescript
+// You can access the store OUTSIDE components!
+const currentUser = useUser.get('name');
+useUser.set('isLogged', true);
+
+// You can even compute data on the fly (Computed State)
+useUser.compute('fullName', ['firstName', 'lastName'], (s) => `${s.firstName} ${s.lastName}`);
+```
+
+## 🚜 Production Strategy: "The Store Folder"
+
+Don't scatter stores everywhere. Create a `src/stores` folder and put your Magnetar files there:
+
+- `auth.ts`
+- `cart.ts`
+- `settings.ts`
+
+Then import them whenever needed. It’s clean, fast, and professional.
+
+## 🧠 Reflection for the Senior Dev
+
+*"Wait, does Magnetar create a new store every time?"*
+Yes, and that's the point! You can have isolated micro-stores for every domain of your app, while still keeping the ability to make them talk to each other. It’s the evolution of the "Atomic State" concept.
+
+---
+
+**Next step:** [Persistence and Safety: Data Never Dies](persistence-and-safety.md)