@adukiorg/anza 0.2.0

package/src/core/security/crypto.js

@@ -0,0 +1,159 @@
+/**
+ * src/core/security/crypto.js
+ *
+ * Web Cryptography Facade.
+ * Offloads all cryptographic functions to standard async SubtleCrypto thread pools,
+ * generating fresh IVs for AES-GCM and enforcing robust key derivation iterations.
+ *
+ * Source: doc 15 — Security Architecture §3
+ */
+
+/**
+ * Returns a cryptographically secure random UUID string.
+ */
+export function uuid() {
+  return crypto.randomUUID();
+}
+
+/**
+ * Digests data into an ArrayBuffer hash using a specified algorithm.
+ */
+export async function hash(data, algo = 'SHA-256') {
+  const buf = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+  return crypto.subtle.digest(algo, buf);
+}
+
+/**
+ * Generates a non-extractable CryptoKey default.
+ */
+export async function generateKey(algo = 'AES-GCM', usages = ['encrypt', 'decrypt'], extractable = false) {
+  let param;
+  if (algo === 'AES-GCM') {
+    param = { name: 'AES-GCM', length: 256 };
+  } else if (algo === 'HMAC') {
+    param = { name: 'HMAC', hash: { name: 'SHA-256' } };
+  } else {
+    param = algo;
+  }
+  return crypto.subtle.generateKey(param, extractable, usages);
+}
+
+/**
+ * Derives an AES-GCM key from a password and salt using PBKDF2 with 600,000 iterations.
+ */
+export async function deriveKey(password, salt, iterations = 600000) {
+  const enc = new TextEncoder();
+  const passwordKey = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(password),
+    'PBKDF2',
+    false,
+    ['deriveBits', 'deriveKey']
+  );
+
+  const saltBuf = typeof salt === 'string' ? enc.encode(salt) : salt;
+
+  return crypto.subtle.deriveKey(
+    {
+      name: 'PBKDF2',
+      salt: saltBuf,
+      iterations,
+      hash: 'SHA-256'
+    },
+    passwordKey,
+    { name: 'AES-GCM', length: 256 },
+    false, // non-extractable by default
+    ['encrypt', 'decrypt']
+  );
+}
+
+/**
+ * Encrypts data using AES-GCM with a fresh 12-byte IV, prepending it to the ciphertext.
+ */
+export async function encrypt(key, data) {
+  const buf = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    buf
+  );
+
+  // Combine IV and Ciphertext for simple storage transit
+  const combined = new Uint8Array(iv.length + ciphertext.byteLength);
+  combined.set(iv, 0);
+  combined.set(new Uint8Array(ciphertext), iv.length);
+  return combined.buffer;
+}
+
+/**
+ * Decrypts a combined IV-ciphertext payload.
+ */
+export async function decrypt(key, combinedData) {
+  const view = new Uint8Array(combinedData);
+  const iv = view.slice(0, 12);
+  const ciphertext = view.slice(12);
+
+  return crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    ciphertext
+  );
+}
+
+function toBase64(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+function fromBase64(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+}
+
+/**
+ * String convenience over `encrypt`: encrypts text and returns a base64 string
+ * (IV + ciphertext) ready for storage or transit.
+ */
+export async function seal(key, text) {
+  const buffer = await encrypt(key, String(text));
+  return toBase64(buffer);
+}
+
+/**
+ * String convenience over `decrypt`: takes a base64 string produced by `seal`
+ * and returns the decoded plaintext string.
+ */
+export async function unseal(key, b64) {
+  const buffer = await decrypt(key, fromBase64(b64));
+  return new TextDecoder().decode(buffer);
+}
+
+/**
+ * Signs data using HMAC or ECDSA signatures.
+ */
+export async function sign(key, data) {
+  const buf = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+  const alg = key.algorithm.name === 'HMAC' 
+    ? { name: 'HMAC' } 
+    : { name: 'ECDSA', hash: { name: 'SHA-256' } };
+
+  return crypto.subtle.sign(alg, key, buf);
+}
+
+/**
+ * Verifies a signature using HMAC or ECDSA.
+ */
+export async function verify(key, signature, data) {
+  const buf = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+  const alg = key.algorithm.name === 'HMAC' 
+    ? { name: 'HMAC' } 
+    : { name: 'ECDSA', hash: { name: 'SHA-256' } };
+
+  return crypto.subtle.verify(alg, key, signature, buf);
+}

package/src/core/security/index.js

@@ -0,0 +1,49 @@
+/**
+ * src/core/security/index.js
+ *
+ * Public security entry point.
+ * Aggregates SubtleCrypto operations, HTML sanitizations, and Permissions API queries.
+ *
+ * Source: doc 15 — Security Architecture §1, §3
+ */
+
+import {
+  uuid,
+  hash,
+  generateKey,
+  deriveKey,
+  encrypt,
+  decrypt,
+  sign,
+  verify
+} from './crypto.js';
+import { sanitize } from './sanitize.js';
+import { query, watch } from './permissions.js';
+
+export const security = {
+  uuid,
+  hash,
+  generateKey,
+  deriveKey,
+  encrypt,
+  decrypt,
+  sign,
+  verify,
+  sanitize,
+  permission: query,
+  watchPermission: watch
+};
+
+export {
+  uuid,
+  hash,
+  generateKey,
+  deriveKey,
+  encrypt,
+  decrypt,
+  sign,
+  verify,
+  sanitize,
+  query as permission,
+  watch as watchPermission
+};

package/src/core/security/missing.md

@@ -0,0 +1,97 @@
+# Security Missing Support
+
+This document tracks remaining support, runtime gaps, type mismatches, and storage/offline synchronization improvements for `src/core/security`. Implemented behavior belongs in `usage.md`; unsupported, under-tested, or performance-gated behavior belongs here until it is built and verified.
+
+---
+
+## 0. Toolchain and Naming Rules
+
+Heavy compilation, static analysis, and code generation belong in `tools/`, not in browser runtime modules.
+
+Current toolchain security requirements:
+- Ensure strict CSP conformance checking at build time.
+- Validate that all HTML insertion sites (sinks) in templates are wrapped in `sanitize` or Trusted Types.
+
+Naming rules for security support:
+- Prefer one-word files: `crypto.js`, `sanitize.js`, `permissions.js`, `index.js`.
+- Plural folders: `tests/`, `types/`.
+- Single-word methods where possible: `uuid`, `hash`, `encrypt`, `decrypt`, `sign`, `verify`, `sanitize`, `permission`.
+
+---
+
+## 1. Critical Runtime and Type Gaps
+
+### 1.1. Missing Trusted Types Integration in Sanitizer
+- **Status**: Runtime gap.
+- **Files**:
+  - `src/core/security/sanitize.js`
+- **Problem**:
+  The `sanitize()` function returns a raw string. When a strict CSP enforces `require-trusted-types-for 'script'`, writing this string to DOM sinks like `innerHTML` throws a `TypeError`. The HTML sanitizer must yield a `TrustedHTML` object wrapped in a named policy (`core-sanitize`) rather than a plain string when Trusted Types are supported by the environment.
+- **Expected Support**:
+  - Create a named Trusted Types policy `core-sanitize` inside `sanitize.js`.
+  - Wrap the sanitized HTML string using the policy to return a `TrustedHTML` object (or fall back to a plain string if the browser does not support Trusted Types).
+  - Implement a `createScriptURL(input)` policy rule to restrict dynamic script source URLs to safe origins.
+
+---
+
+## 2. Storage & Offline Integration Gaps
+
+### 2.1. Direct crypto.randomUUID() Usage in Storage and Offline
+- **Status**: Consistency & synchronization gap.
+- **Files**:
+  - `src/core/offline/clock.js`
+  - `src/core/offline/queue.js`
+  - `src/core/storage/opfs.js`
+- **Problem**:
+  Multiple components call the browser's global `crypto.randomUUID()` directly instead of importing and consuming the centralized `uuid()` utility exported by `core/security`. This prevents unified mocking/stubbing of UUID generation during unit testing and breaks consistency.
+- **Expected Support**:
+  - Refactor `clock.js` to import and use `uuid` from `core/security`.
+  - Refactor `queue.js` to import and use `uuid` from `core/security`.
+  - Refactor `storage/opfs.js` to import and use `uuid` from `core/security`.
+
+### 2.2. Transparent Storage Encryption Interface
+- **Status**: Feature gap.
+- **Files**:
+  - `src/core/storage/index.js`
+  - `src/core/security/crypto.js`
+- **Problem**:
+  Sensitive keys or offline sync payloads stored in IndexedDB or OPFS are written as raw plaintext. A secure offline synchronization layer requires a way to transparently encrypt and decrypt values before they cross the storage boundary.
+- **Expected Support**:
+  - Expose helper utilities in `crypto.js` to securely encrypt and decrypt objects using derived AES-GCM keys.
+
+---
+
+## 3. Test Coverage Gaps
+
+### 3.1. Missing Permissions Watcher Testing
+- **Status**: Test gap.
+- **Files**:
+  - `tests/core/security/permissions.test.js` [NEW]
+- **Needed Coverage**:
+  - Verify that `permission()` queries return states like `'granted'`, `'denied'`, or `'prompt'`.
+  - Verify that `watchPermission()` registers a listener on permission changes, respects AbortSignal abort triggers, and cleans up event listeners correctly.
+
+### 3.2. Missing Signature Verification Testing
+- **Status**: Test gap.
+- **Files**:
+  - `tests/core/security/crypto.test.js`
+- **Needed Coverage**:
+  - Test HMAC and ECDSA key generation, message signing, and signature verification via `sign()` and `verify()`.
+
+---
+
+## 4. Suggested Implementation Order
+
+1. Implement the `core-sanitize` Trusted Types policy inside `src/core/security/sanitize.js`.
+2. Refactor direct `crypto.randomUUID()` calls in `clock.js`, `queue.js`, and `storage/opfs.js` to use `uuid` from `core/security`.
+3. Add permission query/watcher tests in a new file `tests/core/security/permissions.test.js`.
+4. Add sign/verify tests in `tests/core/security/crypto.test.js`.
+
+---
+
+## 5. Done Criteria
+
+This missing-support list is complete when:
+- `sanitize()` returns a `TrustedHTML` object (when supported).
+- Direct `crypto.randomUUID()` calls are replaced with `uuid()` imports.
+- Permission query/watching and cryptographically signing/verifying features are fully tested.

package/src/core/security/permissions.js

@@ -0,0 +1,64 @@
+/**
+ * src/core/security/permissions.js
+ *
+ * Permissions API Facade.
+ * Queries, requests, and watches native browser permission changes,
+ * implementing AbortSignal-gated status change listeners.
+ *
+ * Source: doc 15 — Security Architecture §5
+ */
+
+/**
+ * Queries the browser permission status for a given capability name.
+ */
+export async function query(permissionName) {
+  if (typeof navigator !== 'undefined' && navigator.permissions?.query) {
+    try {
+      // Standard descriptor format (some APIs may require additional fields, handled by consumer)
+      const status = await navigator.permissions.query({ name: permissionName });
+      return status.state; // 'granted' | 'denied' | 'prompt'
+    } catch {
+      return 'denied';
+    }
+  }
+  return 'denied';
+}
+
+/**
+ * Subscribes to changes in a specific permission status.
+ */
+export function watch(permissionName, fn, signal) {
+  if (signal?.aborted) return () => {};
+
+  let activeStatus = null;
+  const listener = () => {
+    if (activeStatus) {
+      fn(activeStatus.state);
+    }
+  };
+
+  const dispose = () => {
+    if (activeStatus) {
+      activeStatus.removeEventListener('change', listener);
+    }
+  };
+
+  if (typeof navigator !== 'undefined' && navigator.permissions?.query) {
+    navigator.permissions
+      .query({ name: permissionName })
+      .then((status) => {
+        if (signal?.aborted) return;
+        activeStatus = status;
+        activeStatus.addEventListener('change', listener);
+      })
+      .catch((err) => {
+        console.warn(`Unable to query permissions watch for "${permissionName}":`, err);
+      });
+  }
+
+  if (signal) {
+    signal.addEventListener('abort', dispose);
+  }
+
+  return dispose;
+}

package/src/core/security/sanitize.js

@@ -0,0 +1,100 @@
+/**
+ * src/core/security/sanitize.js
+ *
+ * HTML Sanitizer wrapper.
+ * Transparently targets browser Sanitizer APIs if available, falling back to a
+ * high-performance DOMParser-based secure sanitization tree that strips unapproved
+ * elements, JavaScript links, and dynamic scripting attributes.
+ *
+ * Source: doc 15 — Security Architecture §2, §4
+ */
+
+const ALLOWED_TAGS = new Set([
+  'a', 'abbr', 'b', 'bdi', 'bdo', 'blockquote', 'br', 'caption', 'cite', 'code',
+  'col', 'colgroup', 'data', 'dd', 'del', 'dfn', 'div', 'dl', 'dt', 'em', 'figcaption',
+  'figure', 'footer', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hr', 'i', 'img',
+  'ins', 'kbd', 'li', 'mark', 'ol', 'p', 'pre', 'q', 'rp', 'rt', 'ruby', 's', 'samp',
+  'section', 'small', 'span', 'strong', 'sub', 'sup', 'table', 'tbody', 'td', 'tfoot',
+  'th', 'thead', 'time', 'tr', 'u', 'ul', 'var', 'wbr'
+]);
+
+const ALLOWED_ATTRS = new Set([
+  'href', 'title', 'src', 'alt', 'width', 'height', 'class', 'id', 'target', 'rel', 'style'
+]);
+
+let policy = null;
+if (typeof window !== 'undefined' && window.trustedTypes) {
+  try {
+    policy = window.trustedTypes.createPolicy('core-sanitize', {
+      createHTML: (html) => html
+    });
+  } catch (err) {
+    console.warn('Trusted Types policy "core-sanitize" registration failed or already registered:', err);
+  }
+}
+
+/**
+ * Sanitizes an HTML string to mitigate XSS vulnerabilities.
+ */
+export function sanitize(html, config = {}) {
+  if (typeof window === 'undefined') return html;
+
+  let sanitized = html;
+
+  // Use experimental browser-native Sanitizer if supported
+  if (typeof globalThis.Sanitizer !== 'undefined') {
+    const sanitizer = new globalThis.Sanitizer(config);
+    const div = document.createElement('div');
+    div.setHTML(html, { sanitizer });
+    sanitized = div.innerHTML;
+  } else {
+    // Resilient fallback utilizing native Document.parseHTMLUnsafe or DOMParser
+    let doc;
+    if (typeof Document !== 'undefined' && typeof Document.parseHTMLUnsafe === 'function') {
+      doc = Document.parseHTMLUnsafe(html);
+    } else {
+      const parser = new DOMParser();
+      doc = parser.parseFromString(html, 'text/html');
+    }
+
+    const filter = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) return;
+
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        const tag = node.tagName.toLowerCase();
+        if (!ALLOWED_TAGS.has(tag)) {
+          node.replaceWith(document.createTextNode(''));
+          return;
+        }
+
+        // Purge dynamic or script attributes
+        for (const attr of [...node.attributes]) {
+          const name = attr.name.toLowerCase();
+          const value = attr.value.trim().toLowerCase();
+
+          // Evict unapproved attributes or javascript: scheme injection vectors
+          if (
+            !ALLOWED_ATTRS.has(name) ||
+            name.startsWith('on') ||
+            (name === 'href' && value.startsWith('javascript:'))
+          ) {
+            node.removeAttribute(attr.name);
+          }
+        }
+
+        // Recursively filter descendants
+        for (const child of [...node.childNodes]) {
+          filter(child);
+        }
+      }
+    };
+
+    for (const child of [...doc.body.childNodes]) {
+      filter(child);
+    }
+
+    sanitized = doc.body.innerHTML;
+  }
+
+  return policy ? policy.createHTML(sanitized) : sanitized;
+}