memorio 4.7.3 → 4.9.5

package/markdown/SECURITY.md

@@ -1,323 +0,0 @@
-# Memorio Security Documentation
-
-> Last Updated: v3.0.2
-
-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 | Without Context | With Context |
-|-----------|-----------------|--------------|
-| Session ID | `crypto.randomUUID()` | Context name |
-| Store Keys | `memorio_store_[uuid]-keyname` | `[contextName]-keyname` |
-| Session Keys | `memorio_session_[uuid]-keyname` | `[contextName]-keyname` |
-| State | In-memory (per-instance) | In-memory (per-instance) |
-
-### Key Prefix Format
-
-```
-// Without context:
-memorio_store-[session-uuid]-username
-memorio_session-[session-uuid]-auth-token
-
-// With context (createContext('user-123')):
-user-123-username
-user-123-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.isolate('tenant-A')
-const tenantB = memorio.isolate('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
-
-### v3.0.2 (Current)
-
-- ✅ Removed esbuild-sass-plugin / esbuild-scss-modules-plugin (SCSS attack vector eliminated)
-- ✅ `store.set()` now blocks function values instead of silently continuing
-- ✅ All `PRIVATE License` headers in `functions/idb/` replaced with `MIT`
-- ✅ `buildPathTracker` dead code removed from state
-- ✅ `Object.freeze(observer)` call removed (undeclared variable, caused `ReferenceError`)
-- ✅ `confirm()` removed from `idb.db.delete()` (no blocking UI calls in libraries)
-- ✅ Fully generated changelog for v3.0.2 across all github docs
-
----
-
-### v2.7.0 - Previous
-
-- ✅ 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 v3.0.2*

package/markdown/SESSION.md

@@ -1,154 +0,0 @@
-# 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.debug(session.get('token')); // "abc123"
-
-// Check persistence
-console.debug(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.debug(`Using ${used} out of ${total} KB`);
-
-// Get total size in characters
-const size = session.size();
-console.debug(`${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/markdown/STATE.md

@@ -1,153 +0,0 @@
-# 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.
-
-> **Classic `import`**: `state` is also a named export.
-> `import { state } from 'memorio'` returns the exact same proxy as `globalThis.state`.
-
----
-
-## Quick Examples
-
-### Example 1: Basic Usage
-
-```javascript
-// Set a value
-state.name = 'Mario';
-state.age = 25;
-
-// Get a value
-console.debug(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.debug(state.items); // [1, 2, 3, 4]
-
-// Nested objects
-state.config = { theme: 'dark', lang: 'en' };
-state.config.theme = 'light';
-
-// List all states
-console.debug(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.debug(path.name); // "user"
-console.debug(path.profile.name); // "user.profile"
-
-// Get full path as string
-console.debug(state.user.__path); // "state.user"
-
-// Protected keys (internal use)
-console.debug(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"
-```