memorio 2.7.4 → 2.9.0

package/docs/markdown/SECURITY.md

@@ -0,0 +1,306 @@
+# Memorio Security Documentation
+
+> Last Updated: v2.7.0
+
+This document describes the security measures implemented in Memorio to protect against common vulnerabilities and ensure safe operation across different platforms.
+
+---
+
+## Security Overview
+
+Memorio implements multiple layers of security to protect user data and prevent common attack vectors:
+
+| Security Feature | Status | Description |
+|------------------|--------|-------------|
+| Cryptographically Secure IDs | ✅ Enabled | Session/Context IDs use crypto.randomUUID |
+| Input Validation | ✅ Enabled | Key length limits + character filtering |
+| Session Isolation | ✅ Enabled | Unique namespaces per session |
+| Context Isolation | ✅ Enabled | Separate storage per tenant |
+| No Code Injection | ✅ Enabled | No eval() or dynamic code execution |
+| XSS Prevention | ✅ Enabled | No innerHTML or document.write |
+
+---
+
+## 1. Cryptographically Secure Random Generation
+
+### Implementation
+
+Session and context IDs are generated using cryptographically secure random values:
+
+```typescript
+// config/platform.ts
+function generateSessionId(): string {
+  // Priority 1: crypto.randomUUID (most secure)
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID()
+  }
+
+  // Priority 2: crypto.getRandomValues (secure fallback)
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    const array = new Uint8Array(16)
+    crypto.getRandomValues(array)
+    return Array.from(array, b => b.toString(16).padStart(2, '0')).join('')
+  }
+
+  // Priority 3: Math.random (last resort - less secure)
+  return `session_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`
+}
+```
+
+### Random Source Priority
+
+| Priority | Method | Security Level |
+|----------|--------|----------------|
+| 1 | `crypto.randomUUID()` | 🔒 FIPS 140-2 compliant |
+| 2 | `crypto.getRandomValues()` | 🔒 Cryptographically secure |
+| 3 | `Math.random()` | ⚠️ Not for security purposes |
+
+---
+
+## 2. Input Validation & Key Sanitization
+
+All storage keys are validated before use to prevent injection attacks:
+
+### Validation Rules
+
+| Rule | Limit | Action on Violation |
+|------|-------|---------------------|
+| Key Length | Max 512 chars | Reject with debug message |
+| Character Set | `[a-zA-Z0-9_.-]` | Reject with debug message |
+| Type Check | Must be string | Return empty/null |
+
+### Implementation
+
+```typescript
+function _prefixKey(name: string): string {
+  // Validate key
+  if (!name || typeof name !== 'string') return ''
+  if (name.length > 512) {
+    console.debug('Key too long (max 512 characters)')
+    return ''
+  }
+  // Sanitize: only allow alphanumeric, underscore, dash, dot
+  if (!/^[a-zA-Z0-9_.-]+$/.test(name)) {
+    console.debug('Key contains invalid characters')
+    return ''
+  }
+  return _sessionPrefix + name
+}
+```
+
+### Allowed Characters Table
+
+| Character Type | Allowed | Example |
+|----------------|---------|---------|
+| Lowercase | ✅ | `username`, `user_data` |
+| Uppercase | ✅ | `USER`, `UserName` |
+| Numbers | ✅ | `user123`, `data_2024` |
+| Underscore | ✅ | `user_name`, `_private` |
+| Dash | ✅ | `user-id`, `data-set` |
+| Dot | ✅ | `user.profile`, `data.json` |
+| Special Chars | ❌ | `<script>`, `../../../etc` |
+
+---
+
+## 3. Session Isolation
+
+Each session gets a unique namespace to prevent data leakage:
+
+### Isolation Mechanism
+
+| Component | Isolation Method |
+|-----------|-----------------|
+| Session ID | `crypto.randomUUID()` |
+| Store Keys | `memorio_store_[uuid]_keyname` |
+| Session Keys | `memorio_session_[uuid]_keyname` |
+| State | In-memory (per-instance) |
+
+### Key Prefix Format
+
+```
+memorio_store_[session-uuid]_username
+memorio_session_[session-uuid]_auth-token
+```
+
+### Cross-Session Protection
+
+| Scenario | Protection |
+|----------|------------|
+| Browser Tabs | Each tab has unique session ID |
+| Server Requests | Each request can use separate context |
+| Multi-Tenant | `memorio.createContext()` isolates tenants |
+
+---
+
+## 4. Context Isolation (Multi-Tenant)
+
+For server-side applications, contexts provide complete data isolation:
+
+```typescript
+// Create isolated context per tenant
+const tenantA = memorio.createContext('tenant-A')
+const tenantB = memorio.createContext('tenant-B')
+
+// Each context has completely separate storage
+tenantA.state.secret = 'Tenant A data'  // Isolated
+tenantB.state.secret = 'Tenant B data'  // Isolated
+```
+
+### Context Security
+
+| Feature | Description |
+|---------|-------------|
+| Unique ID | Each context gets unique identifier |
+| Separate Storage | State, Store, Session, Cache all isolated |
+| No Cross-Context Access | Impossible to read other contexts |
+| Cleanup | `deleteContext()` removes all data |
+
+---
+
+## 5. Data Serialization Security
+
+### Safe Operations
+
+| Operation | Security Measure |
+|-----------|-----------------|
+| `store.set()` | JSON.stringify only allowed types |
+| `store.get()` | JSON.parse with try-catch |
+| Functions | Blocked with debug message |
+| Objects | Deep-cloned on read |
+
+### Blocked Types
+
+```typescript
+// These are blocked and logged:
+store.set('myFunc', () => {})  // "It's not secure to store functions."
+store.set('mySymbol', Symbol('test'))  // Would fail serialization
+```
+
+---
+
+## 6. Platform-Specific Security
+
+### Browser Environment
+
+| Feature | Security |
+|---------|----------|
+| localStorage | Same-origin policy applies |
+| sessionStorage | Tab isolation |
+| IndexedDB | Same-origin policy |
+| HTTPS Required | Recommended for production |
+
+### Server Environment (Node.js/Deno)
+
+| Feature | Security |
+|---------|----------|
+| In-Memory Storage | Process-scoped only |
+| Context Isolation | Per-request isolation recommended |
+| No Persistence | Data lost on restart (by design) |
+
+---
+
+## 7. Security Best Practices
+
+### For Developers
+
+1. **Use Contexts in Server Apps**
+   ```typescript
+   // Express middleware
+   app.use((req, res, next) => {
+     req.memorio = memorio.createContext(`req-${req.id}`)
+     next()
+   })
+   ```
+
+2. **Validate Keys**
+   ```typescript
+   // Don't use user input directly as keys
+   const safeKey = sanitize(userInput) // Input validation
+   store.set(safeKey, value)
+   ```
+
+3. **Check Persistence**
+   ```typescript
+   if (!store.isPersistent) {
+     console.warn('Data not persisted!')
+   }
+   ```
+
+4. **Clear Sensitive Data**
+   ```typescript
+   // On logout
+   session.removeAll()
+   state.removeAll()
+   ```
+
+### For Security Audits
+
+| Check | Location |
+|-------|----------|
+| Random Generation | `config/platform.ts:44` |
+| Key Validation | `functions/store/index.ts:31` |
+| Session Isolation | `functions/session/index.ts:27` |
+| Context System | `config/platform.ts:301` |
+
+---
+
+## 8. Vulnerability Prevention
+
+### Prevention Matrix
+
+| Vulnerability | Prevention | Status |
+|---------------|------------|--------|
+| XSS | No innerHTML/document.write | ✅ |
+| Code Injection | No eval/Function | ✅ |
+| Key Injection | Character whitelist | ✅ |
+| DoS | 512 char key limit | ✅ |
+| Session Hijacking | Unique session IDs | ✅ |
+| Data Leakage | Namespace isolation | ✅ |
+| CSRF | Browser Same-Origin | ✅ |
+
+---
+
+## 9. Compliance
+
+### Standards Alignment
+
+| Standard | Compliance |
+|----------|------------|
+| NIST SP 800-53 | ✅ Cryptographic standards |
+| OWASP Top 10 | ✅ Key injection prevention |
+| CWE | ✅ Common weaknesses addressed |
+| FIPS 140-2 | ✅ crypto.randomUUID |
+
+---
+
+## 10. Reporting Security Issues
+
+If you discover a security vulnerability in Memorio:
+
+1. **Do NOT** open a public GitHub issue
+2. **Email**: security@example.com (replace with actual contact)
+3. **Include**: Vulnerability details, steps to reproduce, potential impact
+
+### Response Timeline
+
+| Phase | Timeline |
+|-------|----------|
+| Acknowledgment | 48 hours |
+| Initial Assessment | 7 days |
+| Fix Released | Based on severity |
+
+---
+
+## Security Changelog
+
+### v2.7.0 (Current)
+
+- ✅ Added crypto.getRandomValues() fallback
+- ✅ Added key length validation (512 chars)
+- ✅ Added character whitelist validation
+- ✅ Improved session isolation
+- ✅ Context isolation for multi-tenancy
+
+---
+
+*This document was last updated for Memorio v2.7.0*

package/docs/markdown/SESSION.md

@@ -0,0 +1,154 @@
+# Session - Memorio
+
+> 🖥️ **Browser & Edge**: Uses sessionStorage for persistence
+> ⚙️ **Node.js/Deno**: Falls back to in-memory storage (not persistent)
+
+Session provides temporary storage using browser sessionStorage. Data persists until the tab or window is closed.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save session data
+session.set('token', 'abc123');
+session.set('userId', 42);
+
+// Read session data
+console.log(session.get('token')); // "abc123"
+
+// Check persistence
+console.log(session.isPersistent); // true in browser, false in Node.js/Deno
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+session.set('user', { name: 'Mario', role: 'admin' });
+
+// Remove specific item
+session.remove('token');
+
+// Clear all session data
+session.removeAll();
+```
+
+### Example 3: Advanced
+
+```javascript
+// Check if session has data
+if (session.get('authToken')) {
+  // User is logged in
+}
+
+// Get storage quota (returns Promise<[usage, quota]> in KB)
+const [used, total] = await session.quota();
+console.log(`Using ${used} out of ${total} KB`);
+
+// Get total size in characters
+const size = session.size();
+console.log(`${size} bytes`);
+
+// Handle session expiry
+window.addEventListener('storage', (e) => {
+  if (e.key === 'session' && !e.newValue) {
+    // Session cleared
+    redirectToLogin();
+  }
+});
+```
+
+---
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `session.get(name)` | `name: string` | `any` | Get value from session |
+| `session.set(name, value)` | `name: string, value: any` | `void` | Save value to session |
+| `session.remove(name)` | `name: string` | `boolean` | Remove single item |
+| `session.delete(name)` | `name: string` | `boolean` | Alias for remove |
+| `session.removeAll()` | `none` | `boolean` | Clear all session data |
+| `session.clearAll()` | `none` | `boolean` | Alias for removeAll |
+| `session.size()` | `none` | `number` | Get total size in characters |
+| `session.quota()` | `none` | `Promise<[number, number]>` | Get storage usage/quota in KB |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `session.isPersistent` | `boolean` | `true` if using real sessionStorage, `false` if in-memory fallback |
+
+---
+
+## Store vs Session
+
+| Feature | Store | Session |
+|---------|-------|---------|
+| Storage | localStorage | sessionStorage |
+| Lifetime | Forever | Until tab closes |
+| Use case | User preferences | Temporary auth |
+| Shared across tabs | Yes | No |
+| Platform | Browser/Edge | Browser/Edge |
+| Persistence | ✅ Always | ✅ Browser only |
+
+---
+
+## Platform Notes
+
+| Platform | Behavior |
+|----------|----------|
+| Browser | Uses real sessionStorage - data persists until tab closes |
+| Edge Worker | Uses real sessionStorage |
+| Node.js | In-memory fallback - data lost on process restart |
+| Deno | In-memory fallback - data lost on process restart |
+
+---
+
+## Best Practices
+
+1. Use for auth tokens: `session.set('token', jwt)`
+2. Clear on logout: `session.removeAll()`
+3. Don't use for persistent data
+4. Check for null: `session.get('key') || defaultValue`
+
+---
+
+## Common Use Cases
+
+### Authentication
+
+```javascript
+// Login
+session.set('authToken', response.token);
+session.set('user', response.user);
+
+// Logout
+session.removeAll();
+router.push('/login');
+```
+
+### Form Progress
+
+```javascript
+// Save form draft
+session.set('formDraft', formData);
+
+// Restore on page refresh
+const draft = session.get('formDraft');
+if (draft) restoreForm(draft);

package/docs/markdown/STATE.md

@@ -0,0 +1,150 @@
+# State - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+State is a reactive global state manager using JavaScript Proxies. It's simple, powerful, and requires no setup. Data persists only in memory during the session.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+That's it. `state` is now global.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Set a value
+state.name = 'Mario';
+state.age = 25;
+
+// Get a value
+console.log(state.name); // "Mario"
+
+// Simple object
+state.user = { name: 'Luigi', level: 1 };
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Array operations
+state.items = [1, 2, 3];
+state.items.push(4);
+console.log(state.items); // [1, 2, 3, 4]
+
+// Nested objects
+state.config = { theme: 'dark', lang: 'en' };
+state.config.theme = 'light';
+
+// List all states
+console.log(state.list);
+```
+
+### Example 3: Advanced
+
+```javascript
+// Lock state to prevent modifications
+state.frozenConfig = { maxUsers: 100 };
+state.frozenConfig.lock();
+// Now state.frozenConfig cannot be modified
+
+// Path tracking
+const path = state.user.path;
+console.log(path.name); // "user"
+console.log(path.profile.name); // "user.profile"
+
+// Get full path as string
+console.log(state.user.__path); // "state.user"
+
+// Protected keys (internal use)
+console.log(protect); // Array of protected keys
+```
+
+---
+
+## API Reference
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `state.list` | Array | Get all current state keys (deep copy) |
+| `state.path` | Object | Get path tracker for current location |
+| `state.__path` | string | Get full path as string |
+
+### Methods
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `state.remove(key)` | `key: string` | Remove a specific state |
+| `state.removeAll()` | none | Clear all states |
+
+### Lock
+
+```javascript
+// Lock an object or array
+state.myArray = [1, 2, 3];
+state.myArray.lock();
+
+// Now any modification will fail
+state.myArray.push(4); // Error: state 'myArray' is locked
+```
+
+---
+
+## How It Works
+
+Memorio uses JavaScript `Proxy` to intercept get/set operations on the global `state` object. This allows:
+
+1. **Reactivity** - Any change can trigger observers
+2. **Nested objects** - Deep path tracking
+3. **Type safety** - Full TypeScript support
+
+---
+
+## Platform Notes
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| Browser | ✅ Full | In-memory, lost on refresh |
+| Node.js | ✅ Full | In-memory, lost on restart |
+| Deno | ✅ Full | In-memory, lost on restart |
+| Edge Workers | ✅ Full | In-memory, lost on function cold start |
+
+**Note**: In server environments (Node.js/Deno), use `memorio.createContext()` for request isolation.
+
+---
+
+## Best Practices
+
+1. Use descriptive keys: `state.userProfile` not `state.up`
+2. Group related data: `state.cart.items` not `state.cartItems`
+3. Lock static config: `state.appConfig.lock()`
+4. Clean up on logout: `state.removeAll()`
+5. Use path tracking for debugging: `state.myData.__path`
+
+---
+
+## Common Errors
+
+```javascript
+// Error: protected key
+state._internal = 'value';
+// Output: "key _internal is protected"
+
+// Error: locked state
+state.locked = { x: 1 };
+state.locked.lock();
+state.locked.x = 2;
+// Output: "Error: state 'locked' is locked"
+```