memorio 4.8.0 → 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/SQLITE.md

@@ -1,181 +0,0 @@
-# SQLite - Memorio
-
-> The `sql.js` package is **optional** — if it is not installed, Memorio loads `sql.js` on first use by injecting the `sql-wasm-browser.js` UMD build from the jsDelivr CDN as a classic `<script>` (which exposes the `initSqlJs` factory on `globalThis`). No bare `import('sql.js')` is ever emitted, so bundlers never resolve the optional dependency at build time. Not available in Node.js/Deno.
-
-SQLite brings a full SQL engine into the browser through [`sql.js`](https://sql.js.org), a port of SQLite to JavaScript via WebAssembly. Memorio loads it **lazily** on first use, so it only affects bundles that actually use the `sqlite` module.
-
-## Installation
-
-```bash
-npm install memorio
-# Optional: install the SQLite engine locally (the default loader fetches it from the CDN)
-npm install sql.js
-```
-
-```javascript
-import 'memorio';
-```
-
-> The default loader injects the sql.js UMD build (`sql-wasm-browser.js`) from the jsDelivr CDN as a classic `<script>`, exposing the `initSqlJs` factory on `globalThis`. This keeps `sql.js` (and its WASM) out of your build graph entirely — it's only fetched when `sqlite` is first used. For production/self-hosted setups, install `sql.js` and configure a custom `loader` (e.g. `sqlite.config({ loader: () => import('sql.js') })` under a bundler), or set the wasm base with `sqlite.config({ wasmUrl })` / `sqlite.config({ locateFile })`.
-
----
-
-## Quick Examples
-
-### Example 1: Basic Usage
-
-```javascript
-// Create an in-memory database and a table
-await sqlite.db.create('myApp');
-await sqlite.query.run('myApp', 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-
-// Insert data
-await sqlite.query.run('myApp', 'INSERT INTO users (name) VALUES (?)', ['Mario']);
-
-// Select data
-const rows = await sqlite.query.select('myApp', 'SELECT * FROM users');
-console.debug(rows); // [{ id: 1, name: 'Mario' }]
-```
-
-### Example 2: CRUD shortcuts
-
-```javascript
-const db = 'store';
-
-await sqlite.db.create(db);
-await sqlite.query.run(db, 'CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL)');
-await sqlite.data.set(db, 'INSERT INTO products (name, price) VALUES (?, ?)', ['Apple', 1.5]);
-await sqlite.data.set(db, 'INSERT INTO products (name, price) VALUES (?, ?)', ['Banana', 0.8]);
-
-// First matching row
-const apple = await sqlite.data.get(db, 'SELECT * FROM products WHERE name = ?', ['Apple']);
-console.debug(apple); // { id: 1, name: 'Apple', price: 1.5 }
-```
-
-### Example 3: Export / Import
-
-```javascript
-await sqlite.db.create('myApp');
-await sqlite.query.run('myApp', 'CREATE TABLE todos (id INTEGER PRIMARY KEY, task TEXT)');
-await sqlite.data.set('myApp', 'INSERT INTO todos (task) VALUES (?)', ['Write docs']);
-
-// Export the in-memory database to a portable binary dump
-const dump = await sqlite.db.export('myApp');
-
-// Later... import it back
-await sqlite.db.import('restored', dump);
-const rows = await sqlite.query.select('restored', 'SELECT * FROM todos');
-```
-
-### Example 4: Engine control
-
-```javascript
-// Configure the wasm location BEFORE first use (sets the locateFile base)
-sqlite.config({ wasmUrl: '/static/sql.js/' });
-
-// Or provide a fully custom loader (e.g. a local/npm build of sql.js)
-sqlite.config({ loader: async () => {
-  return await import('sql.js');   // local install — resolves at runtime
-}});
-
-// Enable automatic persistence of one or more databases (see Example 5)
-sqlite.config({ persistence: true });
-
-// Wait until the engine is ready
-await sqlite.ready;
-console.debug('SQLite version:', sqlite.db.version());
-```
-
-### Example 5: Persistence & dev download
-
-> **Important:** sql.js databases live in **WebAssembly memory** — they are
-> in-memory and **volatile** (lost on page refresh) unless you persist them.
-
-```javascript
-// Opt into auto-persistence at create time (global config or per-create)
-await sqlite.db.create('app', { persistence: true });
-
-await sqlite.query.run('app', 'CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)');
-// writes are snapshotted to localStorage automatically (debounced via updateHook)
-
-await sqlite.db.persist('app');          // force an immediate snapshot
-// After a refresh, reopening restores the data:
-await sqlite.db.create('app', { persistence: true });
-
-// Dev convenience: download the current db as a .sqlite file from the browser
-await sqlite.db.download('app', 'app.sqlite');
-
-// Flush + persist + release the handle
-await sqlite.db.close('app');
-```
-
-Persistence is stored on `store` (localStorage, namespaced per
-`sqlite.config({ namespace })` / memorio context) as a base64 snapshot under
-`memorio:sqlite:db:<ns>:<name>`. It is best-effort: if `store` is unavailable
-the database simply behaves as in-memory.
-
----
-
-## API Reference
-
-### Engine Control
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `sqlite.config(opts)` | `opts: { loader?, locateFile?, wasmUrl?, persistence?, namespace? }` | `sqlite` | Configure the engine. `loader` fully replaces the initializer (default = CDN `<script>`); `locateFile` customizes wasm resolution; `wasmUrl` sets the wasm base directory; `persistence` toggles automatic db snapshots; `namespace` partitions persisted snapshots. Chainable. |
-| `sqlite.db.create(name, opts)` | `name: string, opts?: { data?, persistence? }` | `Database` | Opens/creates a named in-memory db. With `persistence: true` (or global config), a snapshot is restored if present and writes are auto-saved. |
-| `sqlite.db.persist(name)` | `name: string` | `Promise<boolean>` | Force an immediate snapshot of a persisted database to `store`. |
-| `sqlite.db.download(name, filename?)` | `name: string, filename?: string` | `Promise<boolean>` | Dev-only: trigger a browser download of the db as a `.sqlite` file. |
-| `sqlite.db.close(name)` | `name: string` | `Promise<void>` | Persist (if enabled), close, and release the handle. |
-| `sqlite.ready` | none | `Promise<void>` | Resolves once `sql.js` has been initialized. Rejects (and sets `_disabled`) if the engine can't load. |
-| `sqlite.db.version()` | none | `string \| null` | Engine version, available after initialization. |
-| `sqlite._disabled` | none | `boolean` | `true` when the module is disabled (non-browser env / load failure). |
-| `sqlite._warning` | none | `string \| undefined` | Reason text when disabled, if applicable. |
-
-### Database Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `sqlite.db.support()` | none | `boolean` | Check whether SQLite can run in this environment. |
-| `sqlite.db.create(name, opts?)` | `name: string`, `opts?: { data }` | `Promise<Database>` | Create an in-memory database (or reopen one from a binary dump). |
-| `sqlite.db.get(name)` | `name: string` | `Database` | Retrieve an open database handle. |
-| `sqlite.db.delete(name)` | `name: string` | `boolean` | Close and remove a database handle. |
-| `sqlite.db.list()` | none | `string[]` | List open database names. |
-| `sqlite.db.size(name?)` | `name?: string` | `Promise<number>` | Size in bytes of one or all databases. |
-| `sqlite.db.export(name)` | `name: string` | `Promise<Uint8Array>` | Export a database to a binary dump. |
-| `sqlite.db.import(name, data)` | `name: string`, `data` | `Promise<Database>` | Create/replace a database from a binary dump. |
-
-### Query Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `sqlite.query.run(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<number>` | Run a statement that does not return rows (INSERT / UPDATE / DELETE / CREATE). Returns modified-row count. |
-| `sqlite.query.select(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<object[]>` | Run a query and return the rows as plain objects. |
-
-### Data Methods (CRUD shortcuts)
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `sqlite.data.set(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<number>` | Alias of `sqlite.query.run`. |
-| `sqlite.data.get(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<object \| null>` | Alias of `sqlite.query.select` returning the first row (or `null`). |
-
----
-
-## Platform Support
-
-| Platform | Support | Notes |
-|----------|---------|-------|
-| Browser | ✅ Full | Requires WebAssembly + the `sql.js` package (or CDN fallback) |
-| Edge Worker | ⚠️ Limited | WebAssembly may be available; configure a `loader` manually |
-| Node.js | ❌ Not available | Use `store` or `session` instead |
-| Deno | ❌ Not available | Use `store` or `session` instead |
-
----
-
-## Best Practices
-
-1. Configure the wasm path for production: `sqlite.config({ wasmUrl })` or `sqlite.config({ loader })`.
-2. Create one named database per feature and reuse the handle: `const db = await sqlite.db.create('app')`.
-3. Always release databases you no longer need: `sqlite.db.delete('temp')`.
-4. Use `await sqlite.ready` before running statements to ensure the engine is loaded.
-5. Use `?` placeholders and `params` to avoid SQL injection.