@adukiorg/anza 0.2.0

package/src/core/security/usage.md

@@ -0,0 +1,283 @@
+# Native Security Usage Guide
+
+The Native Security layer provides a unified, zero-dependency browser-native security façade covering Web Cryptography, HTML sanitization, Trusted Types, and the Permissions API. All cryptographic operations delegate to the browser's optimized `SubtleCrypto` thread pools. No third-party libraries are required.
+
+Import from the security entry point:
+
+```javascript
+import { security } from '@adukiorg/anza/security';
+```
+
+Or import individual utilities directly:
+
+```javascript
+import { uuid, hash, generateKey, encrypt, decrypt, seal, unseal, sign, verify, sanitize, permission, watchPermission } from '@adukiorg/anza/security';
+```
+
+---
+
+## 1. Choosing an API
+
+| Need | API | Characteristics |
+|---|---|---|
+| Unique correlation ID | `uuid()` | Synchronous, `crypto.randomUUID()`, centralized and mockable |
+| Content hashing | `hash(data, algo)` | `SubtleCrypto.digest`, returns `ArrayBuffer` |
+| AES-GCM encryption | `generateKey`, `encrypt`, `decrypt` | Non-extractable by default, fresh 12-byte IV per encrypt |
+| String encryption (base64) | `seal`, `unseal` | Convenience wrappers over `encrypt`/`decrypt` returning base64 strings |
+| Password-derived key | `deriveKey(pw, salt, iters)` | PBKDF2 with 600,000 iterations, AES-GCM output |
+| Integrity / signing | `sign(key, data)` | HMAC or ECDSA depending on key algorithm |
+| Signature verification | `verify(key, sig, data)` | HMAC or ECDSA depending on key algorithm |
+| Safe HTML output | `sanitize(html)` | DOMParser fallback, Trusted Types when available |
+| Permission query | `permission(name)` | Resolves to `'granted'` \| `'denied'` \| `'prompt'` |
+| Permission watcher | `watchPermission(name, fn, signal)` | AbortSignal-gated change listener |
+
+---
+
+## 2. Unique Identifiers
+
+`uuid()` is the centralized source of cryptographically secure UUIDs across all platform modules. Using it instead of calling `crypto.randomUUID()` directly makes the system mockable in tests.
+
+```javascript
+import { uuid } from '@adukiorg/anza/security';
+
+const id = uuid(); // e.g. "550e8400-e29b-41d4-a716-446655440000"
+```
+
+---
+
+## 3. Hashing
+
+Compute a SHA-256 (or other algorithm) digest of any data:
+
+```javascript
+import { hash } from '@adukiorg/anza/security';
+
+// Hash a string
+const digest = await hash('my-payload');
+console.log(digest instanceof ArrayBuffer); // true — 32 bytes for SHA-256
+
+// Hash binary data with SHA-512
+const buf = new TextEncoder().encode('data');
+const sha512 = await hash(buf, 'SHA-512');
+```
+
+---
+
+## 4. Symmetric Encryption (AES-GCM)
+
+Generates a non-extractable 256-bit AES-GCM key, encrypts data with a fresh 12-byte IV, and prepends the IV to the ciphertext for portability:
+
+```javascript
+import { generateKey, encrypt, decrypt } from '@adukiorg/anza/security';
+
+// Generate a key (non-extractable, in-memory only)
+const key = await generateKey('AES-GCM');
+
+// Encrypt
+const cipher = await encrypt(key, 'Secret message'); // returns ArrayBuffer (IV + ciphertext)
+
+// Decrypt
+const plainBuf = await decrypt(key, cipher);
+const plain = new TextDecoder().decode(plainBuf);
+console.log(plain); // 'Secret message'
+```
+
+---
+
+## 5. String Encryption (Base64 Convenience)
+
+`seal` and `unseal` are string-friendly wrappers over `encrypt`/`decrypt` that return and accept base64-encoded payloads. They are ideal for storing encrypted data in JSON, localStorage, or IndexedDB:
+
+```javascript
+import { generateKey, seal, unseal } from '@adukiorg/anza/security';
+
+const key = await generateKey('AES-GCM');
+
+// Encrypt to a base64 string (IV + ciphertext)
+const sealed = await seal(key, 'Secret message');
+// e.g. "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w=="
+
+// Decrypt from base64 string
+const plain = await unseal(key, sealed);
+console.log(plain); // 'Secret message'
+```
+
+The base64 format is portable and can be safely stored as JSON strings:
+
+```javascript
+await storage.set('secure:session', sealed, 'idb');
+const retrieved = await storage.get('secure:session', 'idb');
+const plain = await unseal(key, retrieved);
+```
+
+---
+
+## 6. Password-Based Key Derivation (PBKDF2)
+
+Derive an AES-GCM key from a user password and a salt using 600,000 PBKDF2 iterations (NIST-recommended):
+
+```javascript
+import { deriveKey, encrypt, decrypt } from '@adukiorg/anza/security';
+
+const key = await deriveKey('UserPassword!', 'unique-salt-string');
+
+// Use the derived key normally
+const cipher = await encrypt(key, 'protected data');
+const buf = await decrypt(key, cipher);
+const text = new TextDecoder().decode(buf);
+```
+
+> [!IMPORTANT]
+> The salt must be unique per user or credential and stored alongside the ciphertext. Never reuse salts across different passwords.
+
+For fast test execution, reduce iterations:
+
+```javascript
+const key = await deriveKey('pw', 'salt', 1000); // for tests only
+```
+
+---
+
+## 7. Signing and Verification
+
+### HMAC (Symmetric Integrity)
+
+```javascript
+import { generateKey, sign, verify } from '@adukiorg/anza/security';
+
+const key = await generateKey('HMAC', ['sign', 'verify']);
+const data = 'message to protect';
+
+const sig = await sign(key, data);        // ArrayBuffer
+const valid = await verify(key, sig, data); // true
+
+const tampered = await verify(key, sig, data + '!'); // false
+```
+
+### ECDSA (Asymmetric Signing)
+
+```javascript
+// Generate ECDSA key pair using SubtleCrypto directly
+const keyPair = await crypto.subtle.generateKey(
+  { name: 'ECDSA', namedCurve: 'P-256' },
+  false,
+  ['sign', 'verify']
+);
+
+const data = 'document-to-sign';
+const sig = await sign(keyPair.privateKey, data);
+const valid = await verify(keyPair.publicKey, sig, data); // true
+```
+
+---
+
+## 8. HTML Sanitization (Trusted Types)
+
+`sanitize()` strips all disallowed tags, event handler attributes, and `javascript:` href links. When the browser supports the Trusted Types API, it wraps the output in a named `TrustedHTML` object (`core-sanitize` policy) to satisfy strict CSP directives:
+
+```javascript
+import { sanitize } from '@adukiorg/anza/security';
+
+// Safe input passes through cleanly
+const safe = String(sanitize('<p class="note"><strong>Hello</strong></p>'));
+// '<p class="note"><strong>Hello</strong></p>'
+
+// Malicious input is cleaned
+const unsafe = String(sanitize('<div><script>alert("xss")</script><img onerror="hack()"></div>'));
+// '<div></div>'
+
+// javascript: href is stripped
+const link = String(sanitize('<a href="javascript:void(0)">click</a>'));
+// '<a>click</a>'
+```
+
+> [!NOTE]
+> The return type is `TrustedHTML | string`. Use `String(sanitize(...))` when you only need the raw string. Pass the raw result directly to DOM sinks that accept `TrustedHTML` under a Trusted Types policy.
+
+> [!WARNING]
+> `sanitize()` is client-side only. It returns the input unchanged when called outside a browser (e.g. Node.js SSR).
+
+---
+
+## 9. Permissions API
+
+### Query Current State
+
+```javascript
+import { permission } from '@adukiorg/anza/security';
+
+const state = await permission('geolocation');
+// 'granted' | 'denied' | 'prompt'
+
+const cam = await permission('camera');
+```
+
+Returns `'denied'` safely for any unrecognized or unsupported permission name.
+
+### Watch for Changes
+
+```javascript
+import { watchPermission } from '@adukiorg/anza/security';
+
+const ctrl = new AbortController();
+
+const dispose = watchPermission('geolocation', (state) => {
+  console.log('Permission changed:', state);
+}, ctrl.signal);
+
+// Later, tear down cleanly:
+ctrl.abort(); // or dispose();
+```
+
+> [!TIP]
+> Always pass an `AbortSignal` to `watchPermission` inside components or views so the watcher is removed automatically when the component is destroyed.
+
+---
+
+## 9. Integration Patterns
+
+### Lifecycle-Gated Watcher in a Custom Element
+
+```javascript
+class MyLocation extends HTMLElement {
+  #ctrl = new AbortController();
+
+  connectedCallback() {
+    watchPermission('geolocation', (state) => {
+      this.dataset.geo = state;
+    }, this.#ctrl.signal);
+  }
+
+  disconnectedCallback() {
+    this.#ctrl.abort();
+  }
+}
+```
+
+### Encrypting and Storing Sensitive Data
+
+```javascript
+import { generateKey, seal, unseal } from '@adukiorg/anza/security';
+import { storage } from '@adukiorg/anza/storage';
+
+// Derive and persist key
+const key = await generateKey('AES-GCM');
+const sealed = await seal(key, JSON.stringify({ token: 'secret' }));
+await storage.set('secure:session', sealed, 'idb');
+
+// Retrieve and decrypt
+const retrieved = await storage.get('secure:session', 'idb');
+const plain = await unseal(key, retrieved);
+const { token } = JSON.parse(plain);
+```
+
+### Sanitize Before Setting innerHTML
+
+```javascript
+import { sanitize } from '@adukiorg/anza/security';
+
+function render(el, userHtml) {
+  // TrustedHTML satisfies Trusted Types sinks
+  el.innerHTML = sanitize(userHtml);
+}
+```

package/src/core/state/derived.js

@@ -0,0 +1,117 @@
+/**
+ * src/core/state/derived.js
+ *
+ * Fine-grained reactive derived state (computed nodes).
+ * Evaluates computations lazily, memoizes results, and dynamically collects
+ * dependency keys by intercepting read accesses during execution.
+ *
+ * Source: doc 08 — State Management §7, §8
+ */
+
+import { setActiveSubscriber, getActiveSubscriber } from './store.js';
+
+export class DerivedValue {
+  #compute;
+  #value;
+  #dependencies = new Set();
+  #dirty = true;
+  #listeners = new Set();
+  #disposers = [];
+
+  constructor(compute) {
+    if (typeof compute !== 'function') {
+      throw new Error('DerivedValue requires a valid compute function');
+    }
+    this.#compute = compute;
+  }
+
+  /**
+   * Retrieves the current computed value (evaluates lazily and memoizes result).
+   */
+  get value() {
+    // Propagate dependency mapping up to parents (for nested derived nodes)
+    const outerSubscriber = getActiveSubscriber();
+    if (outerSubscriber) {
+      for (const dep of this.#dependencies) {
+        outerSubscriber.add(dep);
+      }
+    }
+
+    if (this.#dirty) {
+      this.#recompute();
+    }
+
+    return this.#value;
+  }
+
+  #recompute() {
+    // Revoke previous listeners
+    for (const dispose of this.#disposers) {
+      dispose();
+    }
+    this.#disposers = [];
+    this.#dependencies.clear();
+
+    // Trap active gets inside execution context
+    const previous = getActiveSubscriber();
+    const tracked = new Set();
+    setActiveSubscriber(tracked);
+
+    try {
+      this.#value = this.#compute();
+      this.#dirty = false;
+      this.#dependencies = tracked;
+
+      // Reactively attach to all newly resolved dependency nodes
+      for (const dep of this.#dependencies) {
+        const dispose = dep.store.subscribe(dep.key, () => {
+          this.#markDirty();
+        });
+        this.#disposers.push(dispose);
+      }
+    } finally {
+      setActiveSubscriber(previous);
+    }
+  }
+
+  #markDirty() {
+    if (this.#dirty) return;
+    this.#dirty = true;
+
+    for (const callback of this.#listeners) {
+      try {
+        callback();
+      } catch (err) {
+        console.error('Error executing derived state change subscription:', err);
+      }
+    }
+  }
+
+  /**
+   * Subscribes to updates on this derived state node.
+   */
+  subscribe(callback) {
+    this.#listeners.add(callback);
+    return () => {
+      this.#listeners.delete(callback);
+    };
+  }
+
+  /**
+   * Releases and cleans up active subscriptions.
+   */
+  dispose() {
+    for (const dispose of this.#disposers) {
+      dispose();
+    }
+    this.#disposers = [];
+    this.#listeners.clear();
+  }
+}
+
+/**
+ * Creates a memoized derived state node.
+ */
+export function derived(compute) {
+  return new DerivedValue(compute);
+}

package/src/core/state/index.js

@@ -0,0 +1,23 @@
+/**
+ * src/core/state/index.js
+ *
+ * Public state management namespace.
+ * Bundles reactive in-memory stores, lazy derived derivations,
+ * cross-tab replications, and transactional IndexedDB persistence.
+ *
+ * Source: doc 08 — State Management §2, §15
+ */
+
+import { ReactiveStore, setActiveSubscriber, getActiveSubscriber } from './store.js';
+import { derived } from './derived.js';
+import { sync } from './sync.js';
+import { PlatformStorage, storage } from './persist.js';
+
+export const state = {
+  create: (initial, options) => new ReactiveStore(initial, options),
+  derived,
+  sync,
+  storage
+};
+
+export { ReactiveStore, setActiveSubscriber, getActiveSubscriber, derived, sync, PlatformStorage, storage };

package/src/core/state/missing.md

@@ -0,0 +1,165 @@
+# State Missing Support
+
+This document tracks remaining support, runtime bugs, type mismatches, and performance optimization work for `src/core/state`. Implemented behavior belongs in `usage.md` (or core documentation); unsupported, untyped, or under-tested behavior belongs here until it is built and verified.
+
+---
+
+## 0. Toolchain and Naming Rules
+
+Heavy validation, static analysis, and code generation belong in `tools/`, not in browser runtime modules.
+
+Current toolchain state support requirements:
+- Analyze `state` initialization and usage patterns statically.
+- Detect mutations violating the immutability discipline.
+- Generate unified type definitions for state domains.
+
+Naming rules for state support:
+- Prefer one-word files: `store.js`, `derived.js`, `persist.js`, `sync.js`, `index.js`.
+- Plural folders: `tests/`, `types/`.
+- Single-word methods: `get`, `set`, `batch`, `sync`, `derived`, `clear`, `reset`, `estimate`, `persist`.
+- Single-word events: `change`, `hydrate`, `quota`, `error`.
+- Avoid compound names where single words carry full meaning in context.
+
+---
+
+## 1. Critical Runtime and Type Gaps
+
+### 1.1. Storage Type Mismatches
+- **Status**: Critical mismatch.
+- **Files**:
+  - `types/core/state/index.d.ts`
+  - `src/core/state/persist.js`
+- **Problem**:
+  The type declaration file defines `storage` with `persist(store, options)` and `hydrate(store, name)`. The actual runtime `storage` export is an instance of `PlatformStorage` exposing CRUD and system queries: `get(store, key)`, `set(store, key, val)`, `delete(store, key)`, `query(store, filter)`, `estimate()`, `persist()`, and `isPersisted()`.
+- **Expected Support**:
+  - Align `types/core/state/index.d.ts` to expose the true `PlatformStorage` interface.
+  - Implement helper hooks in the store or `persist.js` to simplify store-wide persistence if required, but maintain structural parity.
+
+### 1.2. Writable Store Event and Helper Omissions
+- **Status**: Runtime gap.
+- **Files**:
+  - `src/core/state/store.js`
+  - `src/core/state/index.js`
+- **Problem**:
+  The State Management specification (§15) defines `store.broadcast(channelName)` as a method directly on the store instance for cross-tab replication. Currently, this functionality is decoupled into a standalone `sync(store, keys, channelName)` function. Similarly, `store.derived(keys, compute)` is specified but not present on the store instance class.
+- **Expected Support**:
+  - Add a delegate helper `broadcast(channelName, keys?)` to `ReactiveStore` mapping directly to the `sync` utility.
+  - Add a delegate helper `derived(keys, compute)` to `ReactiveStore` mapping to `derived(compute)` with key-bound invalidation if preferred, or clean up the API specification.
+
+---
+
+## 2. Persistence Gaps (Storage Quota and Eviction)
+
+### 2.1. Proactive Eviction and Quota Warnings
+- **Status**: Planned but missing.
+- **File**:
+  - `src/core/state/persist.js`
+- **Problem**:
+  The storage engine does not monitor available quota or execute proactive eviction. Large applications risk throwing unhandled `QuotaExceededError` exceptions when writing data.
+- **Expected Support**:
+  - Implement a quota check wrapper on `set()`.
+  - Establish a warning threshold (80% of estimated quota).
+  - Add proactive eviction stages:
+    1. Prune expired cache records based on TTL metadata.
+    2. Evict low-recency records (LRU) using a `lastAccessed` timestamp.
+  - Dispatch a global `quota` warning event if space remains critical.
+
+### 2.2. Write-Through and Write-Ahead Transaction Queues
+- **Status**: Missing support.
+- **File**:
+  - `src/core/state/persist.js`
+- **Problem**:
+  Mutating state is not atomic. A crash between memory writing and database writing leaves inconsistent schemas.
+- **Expected Support**:
+  - Add a transaction-safe queue to handle write-ahead serialization (log first, modify memory on confirmation).
+  - Implement retry logic in the write queue on transient storage lockups or quota exceptions.
+
+---
+
+## 3. Reactivity Performance and Deep Store Support
+
+### 3.1. Deep Reactive Stores
+- **Status**: Enhancement.
+- **File**:
+  - `src/core/state/store.js`
+- **Problem**:
+  `ReactiveStore` only intercepts top-level properties (shallow). Mutating nested objects (e.g., `store.get('user').name = 'alice'`) bypasses reactive traps. Manual structural sharing (e.g., `store.set('user', { ...user, name: 'alice' })`) is error-prone.
+- **Expected Support**:
+  - Add opt-in deep reactivity configuration on store instantiation.
+  - Recursively wrap accessed nested object fields in reactive `Proxy` instances, returning mapped pathways.
+  - Validate that circular references do not crash proxy wrappers.
+
+### 3.2. Optimized Snapshots
+- **Status**: Performance enhancement.
+- **File**:
+  - `src/core/state/store.js`
+- **Problem**:
+  `store.snapshot()` falls back to `JSON.parse(JSON.stringify(...))` when `structuredClone` is missing or if non-serializable objects (like `Map` or `Set`) are stored. This degrades speed in performance-sensitive contexts.
+- **Expected Support**:
+  - Use custom fast-cloning paths for pure data objects.
+  - Delegate serialization for custom collection types within the store configuration.
+
+---
+
+## 4. Build-Time Static Analysis
+
+### 4.1. Immutability Violation Scan
+- **Status**: Planned.
+- **Files**:
+  - `tools/src/extract/runner.rs`
+- **Problem**:
+  In-place mutations of objects retrieved from reactive stores (e.g. `store.get('user').name = 'bob'`) bypasses the `Object.is` check and stops reactive updates. This is hard to debug at runtime.
+- **Expected Support**:
+  - Implement a AST-based checker in `anza` to scan JavaScript sources for store retrieval variables followed by mutation assignments.
+  - Log lint warnings during `scan` and `dev` runs.
+
+### 4.2. Schema Type Generation
+- **Status**: Enhancement.
+- **Files**:
+  - `tools/src/extract/runner.rs`
+- **Expected Support**:
+  - Statically analyze store initializations to output a typed state manifest schema (`state.d.ts`).
+
+---
+
+## 5. Test Coverage Gaps
+
+### 5.1. No Persistence Tests
+- **Status**: Missing coverage.
+- **File**:
+  - `tests/core/state/persist.test.js`
+- **Needed Coverage**:
+  - Database instantiation and migrations.
+  - CRUD operations (`get`, `set`, `delete`, `query`).
+  - Quota estimate mock and persistence hooks.
+  - Eviction stages validation.
+
+### 5.2. Tab Sync Robustness
+- **Status**: Weak coverage.
+- **File**:
+  - `tests/core/state/sync.test.js`
+- **Needed Coverage**:
+  - Re-entrancy and circular echo avoidance.
+  - Proper disposal of broadcast channels.
+
+---
+
+## 6. Suggested Implementation Order
+
+1. Align `types/core/state/index.d.ts` with runtime `PlatformStorage`.
+2. Add `tests/core/state/persist.test.js` to cover basic IndexedDB CRUD operations.
+3. Expose `store.broadcast()` and `store.derived()` delegate methods.
+4. Implement recursive deep proxy wrapper options in `ReactiveStore`.
+5. Implement quota warning thresholds and basic recency-based eviction.
+6. Add build-time immutability violation scanner to `anza`.
+
+---
+
+## 7. Done Criteria
+
+This missing-support list is complete when:
+- Type declarations for `storage` match runtime methods.
+- Persistent local store has comprehensive tests covering IndexedDB operations.
+- Deep reactive stores are optionally configurable and verified.
+- Static scanning tools warn developers of inline store mutations.
+- Eviction and warning systems prevent silent quota failures.