memorio 5.0.0 → 5.1.1

package/SECURITY.md

@@ -1,64 +1,174 @@
-# Security
+# Security & Encryption
 
-Memorio follows NIST and NSA security standards at the enterprise level.
+This document covers Memorio's optional encryption layer, client-side multitenancy, and general security posture. For the short version, see the **Security** section in the main [README](./README.md).
 
-## Security Standards
+---
+
+## Nothing is encrypted by default
+
+This applies to every layer: `state`, `store`, `session`, `idb`, `memory`, `sqlite`. Treat browser storage as client-controlled unless you explicitly opt in.
+
+Core has zero production dependencies. No `eval`, no dynamic code execution, no bundled telemetry, sanitized keys, validated inputs, bounded journal entries, UUID-based session identifiers. Independently checkable via Socket.dev / Snyk.
+
+---
+
+## The encryption layer
+
+Memorio ships an optional encryption layer built on the **Web Crypto API** (`crypto.subtle`): AES-GCM for authenticated encryption, PBKDF2 for password-based key derivation. It is opt-in - no layer encrypts by default, so the common case stays transparent and fast.
+
+All `memorio.encryption` operations are **asynchronous by design** - the Web Crypto API runs cryptographic work on a separate internal thread managed by the browser/runtime, so `deriveKey()`, `encrypt()`, and `decrypt()` return Promises that never block the main thread. PBKDF2 derivation at the NIST SP 800-132-recommended 600,000 iterations typically completes in under 300ms on mid-range hardware. No explicit Web Worker offload is needed.
+
+### Encrypt a value
+
+```ts
+import { memorio } from 'memorio'
+
+// Derive a key from a password (PBKDF2, 600k iterations - NIST SP 800-132)
+const key = await memorio.encryption.deriveKey('my-password', 'per-tenant-salt')
+// or generate one directly, without a password:
+const freshKey = await memorio.encryption.generateKey()
+const freshSalt = memorio.encryption.generateSalt()
+
+// Encrypt → envelope object { __memorio_encrypted, alg, iv, data }
+const envelope = await memorio.encryption.encrypt({ token: 'abc123' }, key)
+
+// Decrypt - wrong key rejects rather than returning garbage
+const original = await memorio.encryption.decrypt(envelope, key)
+// → { token: 'abc123' }
+
+// Check a value before trying to decrypt it
+memorio.encryption.isEncrypted(envelope)     // true - checks the __memorio_encrypted flag
+memorio.encryption.isAvailable()             // false in environments without Web Crypto (e.g. old runtimes)
+```
+
+For the common "encrypt with a password, get a string back" case, skip manual key derivation:
+
+```ts
+const cipherText = await memorio.encryption.encryptWithPassword({ token: 'abc123' }, 'my-password')
+const plain = await memorio.encryption.decryptWithPassword(cipherText, 'my-password')
+```
+
+Both accept/return an envelope object (not a JSON string when you already have a key):
+
+```ts
+const envelope = await memorio.encryption.encrypt({ token: 'abc123' }, key)
+const plain = await memorio.encryption.decrypt(envelope, key) // returns the original value
+```
+
+**Key import/export** for storing CryptoKey material securely (e.g. in an httpOnly cookie):
+
+```ts
+const key = await memorio.encryption.generateKey()
+const { key: b64, iv } = await memorio.encryption.exportKey(key)
+// Store b64 securely, then restore later:
+const restoredKey = await memorio.encryption.importKey(b64, iv)
+```
+
+### Store with at-rest encryption
+
+```ts
+// Per-call encryption (opt-in)
+await store.set('api_token', secretValue, { encrypt: key })
+const token = await store.get('api_token', { decrypt: key })
+
+// Or configure a default key for automatic encryption:
+store.config({ encryptionKey: key })
+await store.set('api_token', secretValue)  // encrypted transparently
+const token = await store.get('api_token') // decrypted transparently
+```
 
-- **NIST Guidelines**: Follows NIST SP 800-53 security controls and NIST Cybersecurity Framework
-- **NSA Standards**: Defense-grade security practices; considers nation-state level threats in risk assessment
+`session` supports the same `config` and per-call opts.
 
-## Supply Chain Security
+> ⚠️ **Sync vs async changes once encryption is on.** Without encryption, `store.get`/`store.set` (and `session`'s equivalents) are synchronous - they return the value directly. As soon as either call touches `encrypt`/`decrypt` (per-call, or because a default `encryptionKey` is configured), both become asynchronous and return a `Promise`. Code written against the plain synchronous API will silently receive a `Promise` instead of a value if encryption is turned on later - always `await` `store.get`/`store.set` defensively if there's any chance encryption gets enabled down the line.
 
-- **Socket.dev**: Minimum target score 90%; all alarms must be resolved before release
-- **Dependency Management**: Zero production dependencies (fully dependency-free); dev dependencies audited regularly
-- **Prohibited**: No `eval()` usage, no encrypted/obfuscated code in builds, no hardcoded secrets
+---
+
+## Contexts are not authorization
+
+```ts
+memorio.createContext('tenant-123')
+```
+
+Contexts organize and isolate application concerns by namespace-prefixing keys - they are **not** a security boundary. Any script running in the same JS runtime can attempt operations against another context. Real tenant isolation belongs at the auth/backend layer.
+
+---
+
+## Encrypted multitenancy
 
-## Code Security
+Pass an `encryptionKey` to `createContext()` and the tenant's isolated `store`/`session` automatically encrypt on write and decrypt on read:
 
-- No hardcoded credentials or API keys
-- Secure random session ID generation (`crypto.randomUUID` → `crypto.getRandomValues` → fallback)
-- Input validation on all public APIs
-- XSS prevention on DevTools data export
-- Property-based access control on global objects (`Object.defineProperty` with `enumerable: false`)
+```ts
+const tenantKey = await memorio.encryption.deriveKey(tenantPassword, tenantSalt)
 
-## OWASP Compliance
+const ctx = memorio.createContext('tenant-123', { encryptionKey: tenantKey })
 
-Addresses OWASP Top 10 (2021):
-- A01:2021 - Broken Access Control (global object protection, property locks)
-- A02:2021 - Cryptographic Failures (crypto.randomUUID for session IDs)
-- A03:2021 - Injection (CSS sanitization in devtools)
-- A05:2021 - Security Misconfiguration (minimal surface area, no bundled secrets)
-- A06:2021 - Vulnerable and Outdated Components (regular npm audit, Socket.dev)
-- A07:2021 - Identification and Authentication Failures (N/A - library, no auth)
-- A08:2021 - Software and Data Integrity Failures (strict tsconfig, lock files)
-- A09:2021 - Security Logging and Monitoring Failures (DevTools inspect, Logger module)
-- A10:2021 - Server-Side Request Forgery (N/A - no network requests)
+// Values are encrypted at rest within this context's namespace
+await ctx.store.set('secrets', { apiKey: '…' })
+const secrets = await ctx.store.get('secrets')  // decrypted transparently
 
-## Global API Security
+// Another tenant with a different key can't read this data
+const otherCtx = memorio.createContext('tenant-456', { encryptionKey: otherKey })
+const leaked = await otherCtx.store.get('memorio_store_secrets')  // fails to decrypt
+```
+
+This adds a cryptographic wall on top of the namespace prefix: even if a tenant's key prefix is guessed, the ciphertext is unreadable without the key. It still doesn't replace backend authorization - see above.
+
+> ⚠️ **`cache` is never encrypted, even inside an encrypted context.** `createContext(name, { encryptionKey })` only encrypts that context's `store` and `session` - its `cache` stays volatile, in-memory, and in plaintext regardless. Don't put anything in `ctx.cache` you wouldn't put in unencrypted `cache`.
+
+`memorio.isolate()` is a thin alias for `createContext()` and accepts the same `{ encryptionKey }` option.
+
+> **Key management is yours.** Derive keys from authenticated session material or generate them with `memorio.encryption.generateKey()`. Never hardcode keys in client bundles.
+
+---
 
-Memorio does **not** expose its APIs on `globalThis` by default. The opt-in
-entrypoint `import 'memorio/global'` installs `state`, `store`, `session`,
-`cache`, `idb`, `sqlite`, `observer`, and `useObserver` on `globalThis`.
-This is an explicit consumer choice - not inferred from `NODE_ENV` or
-bundler environment variables.
+## Global API security
+
+Memorio does **not** expose its APIs on `globalThis` by default. The opt-in entrypoint `import 'memorio/global'` installs `state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`, and `useObserver` on `globalThis` - this is an explicit consumer choice, never inferred from `NODE_ENV` or bundler environment variables.
 
 For application code, prefer explicit named imports:
 
-```js
+```ts
 import { state } from 'memorio'
 ```
 
-See [SECURITY-HARDENING.md](./SECURITY-HARDENING.md) for a full hardening
-guide covering storage encryption, context isolation, logger data capture,
-and platform capability assumptions.
+---
+
+## Code-level hardening
+
+- No hardcoded credentials, API keys, or secrets anywhere in the codebase or build output.
+- Session IDs use a secure random source with graceful fallback: `crypto.randomUUID` → `crypto.getRandomValues` → a documented fallback if neither is available.
+- Public APIs validate their inputs rather than trusting caller-supplied shapes.
+- Global objects installed via `memorio/global` use `Object.defineProperty` with `enumerable: false` where applicable, rather than plain assignment.
+- No obfuscated or minified-beyond-readability code shipped in a way that would hide behavior from review.
+
+---
+
+## Supply chain
 
-If you find a security vulnerability:
+- Zero production dependencies in core - nothing to audit transitively for the parts you actually ship.
+- Dev dependencies are audited periodically (`npm audit` and equivalent).
+- Package integrity is checkable independently via Socket.dev / Snyk before you adopt a given version.
 
-1. Email [Dario Passariello](mailto:dariopassarielloa@gmail.com)
-2. Or visit https://dario.passariello.ca/contact/
+> If you require a specific minimum Socket.dev/Snyk score or a documented audit trail as part of a procurement process, verify the current score yourself at adoption time - this document doesn't pin a number that could go stale.
 
-Do not open public issues for security vulnerabilities.
+---
+
+## Reporting a vulnerability
+
+Please don't open a public issue for a security vulnerability. Instead:
+
+1. Email [Dario Passariello](mailto:dariopassarielloa@gmail.com), or
+2. Use the contact form at https://dario.passariello.ca/contact/
 
 ---
-*Document version: 2.0 - Last updated: 2026-05-19*
-*Owner: BigLogic Security Team*
+
+## Enterprise compliance notes
+
+| Concern | What you get | Impact |
+| --- | --- | --- |
+| **Opt-in encryption** | `memorio.encryption` provides AES-GCM + PBKDF2. `store`/`session` and encrypted contexts support automatic encrypt-on-write/decrypt-on-read. | Not encrypted by default - you must opt in via `store.config({ encryptionKey })` or `createContext(id, { encryptionKey })`. Without it, PII, tokens, and regulated data (GDPR/HIPAA) are at rest in plaintext. Enabling it also changes the calling convention - see the sync/async warning above. |
+| **Client-side multitenancy** | `createContext(id, { encryptionKey })` provides namespace + cryptographic isolation between tenants. | Still **not** a security boundary - any script in the same JS runtime can attempt context operations. Encryption makes cross-tenant reads cryptographically hard, but real authorization must live on the backend. |
+| **DevTools** | Expose data for development only. | Only active when you opt into `memorio/global`; never ship enabled in production. |
+| **Formal compliance frameworks (NIST, OWASP, etc.)** | No formal third-party audit or certification has been published for this project. | If your procurement process requires a certified compliance framework, commission an independent audit rather than relying on self-declared conformance - see [When to use something else](./README.md#when-to-use-something-else) in the README. |
+
+If any of these gaps block adoption, keep Memorio for memory/state lifecycle and pair it with a dedicated secrets manager or backend-enforced authorization for the pieces it explicitly doesn't cover.

package/SUMMARY.md

@@ -29,7 +29,7 @@
 
 | File | Cosa documenta |
 |---|---|
-| `AUDIT-REPORT.md` | Audit di sicurezza/performance/affidabilità/qualità del codice per la v4.9.5 (datato 2026-09-06), con azioni correttive già applicate. |
+| `AUDIT-REPORT.md` | Audit di sicurezza/performance/affidabilità/qualità del codice per la v5.1.0 (datato 2026-09-06), con azioni correttive già applicate. |
 | `CACHE.md` | Reference della cache in-memory: API, quando usarla, limiti. |
 | `CHANGELOG.md` | Storico versioni dalla v2.5.0 alla `Unreleased`, con bugfix, refactoring e note di sicurezza per ogni release. |
 | `DEVTOOLS.md` | Strumenti di debug da console del browser per ispezionare/gestire lo stato di Memorio. |

package/adr/001-state-proxy-model.md

@@ -1,96 +1,95 @@
-# ADR-001: State Proxy Model
-
-> **Status:** Accepted
-> **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
-
-## Context
-
-Memorio's reactive state is built on a JavaScript `Proxy`. Every read of
-a nested object re-wraps the child in a Proxy so that deep
-`set`/`delete` traps fire and dispatch events. The design must answer:
-
-- How are proxy wrappers cached to avoid exponential allocation on
-  repeated reads?
-- What is the reference-identity contract between the proxy and the
-  raw target?
-- Which property names are reserved and cannot be used as state keys?
-- How are non-plain objects (Date, Set, Map, functions) handled?
-
-## Assumptions
-
-- The Proxy target is always a plain `Object` or `Array`.
-- A single `buildProxy` invocation creates one Proxy per raw object.
-- The Proxy is shared across all import paths via `globalThis`
-  singletons (see ADR-006).
-- `__DEV__` is a build-time constant (replaced to `false` in
-  production, `true` in dev/test).
-
-## Decision
-
-### Wrapper caching
-
-`buildProxy` caches the wrapper in a `WeakMap<rawTarget, proxyWrapper>`.
-On every `get` trap, after unwrapping with `TARGET`, the result is looked
-up in the cache; if present, the existing wrapper is returned instead of
-allocating a new one. This keeps repeated nested reads at O(1) in
-allocation and O(1) in proxy depth.
-
-### Reference identity
-
-- `TARGET` is a `Symbol` accessor on the proxy that returns the raw
-  underlying target. `state[TARGET]` === raw root.
-- `state.a[TARGET]` === raw target's `a` property.
-- `JSON.stringify(proxy)` works because `ownKeys` and
-  `getOwnPropertyDescriptor` delegate to `Reflect`.
-- `deepRaw(value)` unwraps all Memorio proxies recursively using
-  `TARGET` and a `WeakSet` for cycle safety, returning a plain clone
-  with no wrapper references.
-
-### Reserved property names
-
-`protect` array in `core/internal.ts` reserves these keys on the root
-`state` proxy:
-
-```
-list, state, store, idb, cache, sqlite, observer, useObserver,
-remove, removeAll, _platform, _capabilities, _sessionId
-```
-
-Setting any of these keys as state data is rejected by the `set` trap
-with a console error. Attempting to set any `_`-prefixed key that
-collides with internal bookkeeping is also guarded.
-
-### Non-plain objects
-
-- `Date`, `Set`, `Map`, `RegExp`, functions, and other non-plain
-  instances are returned by reference — they are **not** re-wrapped in a
-  Proxy.
-- `deepRaw` only traverses `Object` and `Array` constructors; all other
-  types are returned by reference.
-
-### Path tracking
-
-Every `get` trap for a string property sets `internal.lastAccessedPath`
-to the full dotted path (`state.foo.bar`). When
-`internal.tracking` is true, the path is also added to
-`internal.trackedPaths`.
-
-## Consequences
-
-- **Positive:** O(1) wrapper allocation on repeated nested reads; no
-  proxy-depth accumulation on spread updates (regression tested).
-- **Positive:** `TARGET` symbol prevents prototype-pollution attacks
-  via `__proto__`/`constructor`/`prototype` because those are string
-  keys that are simply treated as data keys on the raw target.
-- **Positive:** `deepRaw` produces clean data for persistence and
-  snapshots without leaking proxy wrappers.
-- **Negative:** The `WeakMap` cache is per-module-instance, but since
-  the proxy target is a singleton on `globalThis`, the cache is
-  effectively shared across import paths.
-- **Negative:** Non-plain objects cannot be deeply observed for inner
-  mutations — this is an accepted limitation documented in the API.
-
-## Compliance tests
-
-- `tests/vitest/tests/contracts/adr-001-state.test.ts`
+# ADR-001: State Proxy Model
+
+> **Status:** Accepted
+> **Date:** 2026-09-12
+
+## Context
+
+Memorio's reactive state is built on a JavaScript `Proxy`. Every read of
+a nested object re-wraps the child in a Proxy so that deep
+`set`/`delete` traps fire and dispatch events. The design must answer:
+
+- How are proxy wrappers cached to avoid exponential allocation on
+  repeated reads?
+- What is the reference-identity contract between the proxy and the
+  raw target?
+- Which property names are reserved and cannot be used as state keys?
+- How are non-plain objects (Date, Set, Map, functions) handled?
+
+## Assumptions
+
+- The Proxy target is always a plain `Object` or `Array`.
+- A single `buildProxy` invocation creates one Proxy per raw object.
+- The Proxy is shared across all import paths via `globalThis`
+  singletons (see ADR-006).
+- `__DEV__` is a build-time constant (replaced to `false` in
+  production, `true` in dev/test).
+
+## Decision
+
+### Wrapper caching
+
+`buildProxy` caches the wrapper in a `WeakMap<rawTarget, proxyWrapper>`.
+On every `get` trap, after unwrapping with `TARGET`, the result is looked
+up in the cache; if present, the existing wrapper is returned instead of
+allocating a new one. This keeps repeated nested reads at O(1) in
+allocation and O(1) in proxy depth.
+
+### Reference identity
+
+- `TARGET` is a `Symbol` accessor on the proxy that returns the raw
+  underlying target. `state[TARGET]` === raw root.
+- `state.a[TARGET]` === raw target's `a` property.
+- `JSON.stringify(proxy)` works because `ownKeys` and
+  `getOwnPropertyDescriptor` delegate to `Reflect`.
+- `deepRaw(value)` unwraps all Memorio proxies recursively using
+  `TARGET` and a `WeakSet` for cycle safety, returning a plain clone
+  with no wrapper references.
+
+### Reserved property names
+
+`protect` array in `core/internal.ts` reserves these keys on the root
+`state` proxy:
+
+```
+list, state, store, idb, cache, sqlite, observer, useObserver,
+remove, removeAll, _platform, _capabilities, _sessionId
+```
+
+Setting any of these keys as state data is rejected by the `set` trap
+with a console error. Attempting to set any `_`-prefixed key that
+collides with internal bookkeeping is also guarded.
+
+### Non-plain objects
+
+- `Date`, `Set`, `Map`, `RegExp`, functions, and other non-plain
+  instances are returned by reference - they are **not** re-wrapped in a
+  Proxy.
+- `deepRaw` only traverses `Object` and `Array` constructors; all other
+  types are returned by reference.
+
+### Path tracking
+
+Every `get` trap for a string property sets `internal.lastAccessedPath`
+to the full dotted path (`state.foo.bar`). When
+`internal.tracking` is true, the path is also added to
+`internal.trackedPaths`.
+
+## Consequences
+
+- **Positive:** O(1) wrapper allocation on repeated nested reads; no
+  proxy-depth accumulation on spread updates (regression tested).
+- **Positive:** `TARGET` symbol prevents prototype-pollution attacks
+  via `__proto__`/`constructor`/`prototype` because those are string
+  keys that are simply treated as data keys on the raw target.
+- **Positive:** `deepRaw` produces clean data for persistence and
+  snapshots without leaking proxy wrappers.
+- **Negative:** The `WeakMap` cache is per-module-instance, but since
+  the proxy target is a singleton on `globalThis`, the cache is
+  effectively shared across import paths.
+- **Negative:** Non-plain objects cannot be deeply observed for inner
+  mutations - this is an accepted limitation documented in the API.
+
+## Compliance tests
+
+- `tests/vitest/tests/contracts/adr-001-state.test.ts`