@jxrstudios/jxr 1.0.3 → 1.0.5

package/src/web-crypto.ts

@@ -0,0 +1,279 @@
+/**
+ * JXR.js — Web Crypto Engine
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Design: LavaFlow OS — Thermal Precision + Edge Command
+ * Layer: Core Runtime / Security
+ *
+ * Architecture:
+ *   Universal Web Crypto API wrapper providing:
+ *   - Module integrity verification (SHA-256/SHA-384 hashing)
+ *   - Signed module manifests (ECDSA P-256)
+ *   - Encrypted module caching (AES-GCM 256)
+ *   - Key derivation for per-project isolation (HKDF)
+ *   - Random nonce generation for replay protection
+ *
+ * All operations use the native SubtleCrypto API — no dependencies,
+ * runs in any modern browser, Cloudflare Worker, or Deno runtime.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+const subtle = globalThis.crypto.subtle;
+
+export interface ModuleHash {
+  algorithm: 'SHA-256' | 'SHA-384' | 'SHA-512';
+  digest: string; // hex-encoded
+  size: number;
+  timestamp: number;
+}
+
+export interface SignedManifest {
+  modules: Record<string, ModuleHash>;
+  projectId: string;
+  version: string;
+  signedAt: number;
+  signature: string; // base64url-encoded ECDSA signature
+  publicKey: string; // base64url-encoded SPKI public key
+}
+
+export interface EncryptedModule {
+  ciphertext: string; // base64url
+  iv: string;         // base64url, 12 bytes for AES-GCM
+  tag: string;        // base64url, 16 bytes auth tag
+  keyId: string;
+}
+
+export interface CryptoKeyPair {
+  publicKey: CryptoKey;
+  privateKey: CryptoKey;
+  publicKeyExported: string; // base64url SPKI
+}
+
+/**
+ * JXRCrypto — Universal Web Crypto API abstraction
+ */
+export class JXRCrypto {
+  private signingKeyPair: CryptoKeyPair | null = null;
+  private encryptionKeys: Map<string, CryptoKey> = new Map();
+  private hashCache: Map<string, ModuleHash> = new Map();
+
+  /** Generate an ECDSA P-256 signing key pair for module manifests */
+  async generateSigningKeyPair(): Promise<CryptoKeyPair> {
+    const keyPair = await subtle.generateKey(
+      { name: 'ECDSA', namedCurve: 'P-256' },
+      true,
+      ['sign', 'verify']
+    );
+
+    const spki = await subtle.exportKey('spki', keyPair.publicKey);
+    const publicKeyExported = this.toBase64Url(spki);
+
+    this.signingKeyPair = {
+      publicKey: keyPair.publicKey,
+      privateKey: keyPair.privateKey,
+      publicKeyExported,
+    };
+
+    return this.signingKeyPair;
+  }
+
+  /** Hash a module's source code for integrity verification */
+  async hashModule(
+    source: string,
+    algorithm: 'SHA-256' | 'SHA-384' | 'SHA-512' = 'SHA-256'
+  ): Promise<ModuleHash> {
+    const cacheKey = `${algorithm}:${source.length}:${source.slice(0, 64)}`;
+    const cached = this.hashCache.get(cacheKey);
+    if (cached) return cached;
+
+    const encoded = new TextEncoder().encode(source);
+    const hashBuffer = await subtle.digest(algorithm, encoded);
+    const digest = this.toHex(hashBuffer);
+
+    const result: ModuleHash = {
+      algorithm,
+      digest,
+      size: encoded.byteLength,
+      timestamp: Date.now(),
+    };
+
+    this.hashCache.set(cacheKey, result);
+    return result;
+  }
+
+  /** Verify a module's integrity against a known hash */
+  async verifyModule(source: string, expected: ModuleHash): Promise<boolean> {
+    const actual = await this.hashModule(source, expected.algorithm);
+    return actual.digest === expected.digest;
+  }
+
+  /** Sign a module manifest with ECDSA P-256 */
+  async signManifest(
+    modules: Record<string, ModuleHash>,
+    projectId: string,
+    version: string
+  ): Promise<SignedManifest> {
+    if (!this.signingKeyPair) {
+      await this.generateSigningKeyPair();
+    }
+
+    const manifest = {
+      modules,
+      projectId,
+      version,
+      signedAt: Date.now(),
+    };
+
+    const data = new TextEncoder().encode(JSON.stringify(manifest));
+    const signatureBuffer = await subtle.sign(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      this.signingKeyPair!.privateKey,
+      data
+    );
+
+    return {
+      ...manifest,
+      signature: this.toBase64Url(signatureBuffer),
+      publicKey: this.signingKeyPair!.publicKeyExported,
+    };
+  }
+
+  /** Verify a signed manifest */
+  async verifyManifest(manifest: SignedManifest): Promise<boolean> {
+    try {
+      const spki = this.fromBase64Url(manifest.publicKey);
+      const publicKey = await subtle.importKey(
+        'spki',
+        spki,
+        { name: 'ECDSA', namedCurve: 'P-256' },
+        false,
+        ['verify']
+      );
+
+      const { signature, publicKey: _pk, ...rest } = manifest;
+      const data = new TextEncoder().encode(JSON.stringify(rest));
+      const sigBuffer = this.fromBase64Url(signature);
+
+      return await subtle.verify(
+        { name: 'ECDSA', hash: 'SHA-256' },
+        publicKey,
+        sigBuffer,
+        data
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /** Generate or retrieve an AES-GCM-256 encryption key for a project */
+  async getEncryptionKey(keyId: string, projectSeed?: string): Promise<CryptoKey> {
+    const existing = this.encryptionKeys.get(keyId);
+    if (existing) return existing;
+
+    let key: CryptoKey;
+
+    if (projectSeed) {
+      // Derive key from project seed using HKDF
+      const seedBytes = new TextEncoder().encode(projectSeed);
+      const baseKey = await subtle.importKey('raw', seedBytes, 'HKDF', false, ['deriveKey']);
+      const salt = new TextEncoder().encode(`jxr-project-${keyId}`);
+      const info = new TextEncoder().encode('JXR.js Module Cache v1');
+
+      key = await subtle.deriveKey(
+        { name: 'HKDF', hash: 'SHA-256', salt, info },
+        baseKey,
+        { name: 'AES-GCM', length: 256 },
+        false,
+        ['encrypt', 'decrypt']
+      );
+    } else {
+      key = await subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, [
+        'encrypt',
+        'decrypt',
+      ]);
+    }
+
+    this.encryptionKeys.set(keyId, key);
+    return key;
+  }
+
+  /** Encrypt a module for secure caching */
+  async encryptModule(source: string, keyId: string): Promise<EncryptedModule> {
+    const key = await this.getEncryptionKey(keyId);
+    const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+    const encoded = new TextEncoder().encode(source);
+
+    const cipherBuffer = await subtle.encrypt({ name: 'AES-GCM', iv }, key, encoded);
+
+    // AES-GCM appends 16-byte auth tag to ciphertext
+    const ciphertext = cipherBuffer.slice(0, cipherBuffer.byteLength - 16);
+    const tag = cipherBuffer.slice(cipherBuffer.byteLength - 16);
+
+    return {
+      ciphertext: this.toBase64Url(ciphertext),
+      iv: this.toBase64Url(iv.buffer),
+      tag: this.toBase64Url(tag),
+      keyId,
+    };
+  }
+
+  /** Decrypt a cached module */
+  async decryptModule(encrypted: EncryptedModule): Promise<string> {
+    const key = await this.getEncryptionKey(encrypted.keyId);
+    const iv = this.fromBase64Url(encrypted.iv);
+    const ciphertext = this.fromBase64Url(encrypted.ciphertext);
+    const tag = this.fromBase64Url(encrypted.tag);
+
+    // Reassemble ciphertext + tag for AES-GCM
+    const combined = new Uint8Array(ciphertext.byteLength + tag.byteLength);
+    combined.set(new Uint8Array(ciphertext));
+    combined.set(new Uint8Array(tag), ciphertext.byteLength);
+
+    const plainBuffer = await subtle.decrypt({ name: 'AES-GCM', iv }, key, combined);
+    return new TextDecoder().decode(plainBuffer);
+  }
+
+  /** Generate a cryptographically secure random nonce */
+  generateNonce(bytes = 16): string {
+    const nonce = globalThis.crypto.getRandomValues(new Uint8Array(bytes));
+    return this.toBase64Url(nonce.buffer);
+  }
+
+  /** Generate a project-unique ID using Web Crypto */
+  async generateProjectId(name: string, timestamp: number): Promise<string> {
+    const data = new TextEncoder().encode(`${name}:${timestamp}`);
+    const hash = await subtle.digest('SHA-256', data);
+    return this.toHex(hash).slice(0, 16);
+  }
+
+  // ─── Encoding utilities ───────────────────────────────────────────────────
+
+  private toHex(buffer: ArrayBuffer): string {
+    return Array.from(new Uint8Array(buffer))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  private toBase64Url(buffer: ArrayBuffer): string {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (let i = 0; i < bytes.byteLength; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  private fromBase64Url(str: string): ArrayBuffer {
+    const padded = str.replace(/-/g, '+').replace(/_/g, '/');
+    const padLength = (4 - (padded.length % 4)) % 4;
+    const base64 = padded + '='.repeat(padLength);
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+  }
+}
+
+/** Singleton instance */
+export const jxrCrypto = new JXRCrypto();

package/src/worker-pool.ts

@@ -0,0 +1,321 @@
+/**
+ * JXR.js — Worker Pool Engine
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Design: LavaFlow OS — Thermal Precision + Edge Command
+ * Layer: Core Runtime / Worker Orchestration
+ *
+ * Architecture:
+ *   WorkerPool manages a fleet of Web Workers for parallel task execution.
+ *   Tasks are dispatched via a priority queue and results streamed back
+ *   through a structured message protocol. Each worker is isolated with
+ *   its own module scope, enabling true parallelism without shared state.
+ *
+ * Performance targets:
+ *   - Task dispatch latency: <1ms
+ *   - Worker spawn time: <5ms (pre-warmed pool)
+ *   - Throughput: saturate all available CPU cores
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+export type WorkerStatus = 'idle' | 'busy' | 'error' | 'terminated';
+export type TaskPriority = 'critical' | 'high' | 'normal' | 'low';
+
+export interface WorkerTask<T = unknown, R = unknown> {
+  id: string;
+  type: string;
+  payload: T;
+  priority: TaskPriority;
+  timestamp: number;
+  resolve: (result: R) => void;
+  reject: (error: Error) => void;
+  timeoutMs?: number;
+}
+
+export interface WorkerMetrics {
+  workerId: string;
+  status: WorkerStatus;
+  tasksCompleted: number;
+  tasksFailed: number;
+  avgLatencyMs: number;
+  lastActiveAt: number;
+  cpuLoad: number;
+}
+
+export interface PoolMetrics {
+  totalWorkers: number;
+  idleWorkers: number;
+  busyWorkers: number;
+  queueDepth: number;
+  throughputPerSec: number;
+  avgLatencyMs: number;
+  totalTasksCompleted: number;
+}
+
+interface WorkerEntry {
+  worker: Worker;
+  status: WorkerStatus;
+  currentTaskId: string | null;
+  metrics: WorkerMetrics;
+  latencyHistory: number[];
+}
+
+const PRIORITY_WEIGHTS: Record<TaskPriority, number> = {
+  critical: 4,
+  high: 3,
+  normal: 2,
+  low: 1,
+};
+
+/**
+ * WorkerPool — Pre-warmed, priority-aware Web Worker fleet
+ */
+export class WorkerPool {
+  private workers: Map<string, WorkerEntry> = new Map();
+  private taskQueue: WorkerTask[] = [];
+  private pendingTasks: Map<string, WorkerTask> = new Map();
+  private metricsHistory: number[] = [];
+  private throughputWindow: number[] = [];
+  private readonly maxWorkers: number;
+  private readonly workerScript: string;
+  private taskCounter = 0;
+  private listeners: Map<string, Set<(metrics: PoolMetrics) => void>> = new Map();
+
+  constructor(workerScript: string, maxWorkers?: number) {
+    this.workerScript = workerScript;
+    this.maxWorkers = maxWorkers ?? Math.max(2, (navigator.hardwareConcurrency ?? 4) - 1);
+    this.prewarm();
+  }
+
+  /** Pre-warm the pool to eliminate cold-start latency */
+  private prewarm(): void {
+    const initialCount = Math.min(2, this.maxWorkers);
+    for (let i = 0; i < initialCount; i++) {
+      this.spawnWorker();
+    }
+  }
+
+  private spawnWorker(): string {
+    const workerId = `worker-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const worker = new Worker(this.workerScript, { type: 'module' });
+
+    const entry: WorkerEntry = {
+      worker,
+      status: 'idle',
+      currentTaskId: null,
+      latencyHistory: [],
+      metrics: {
+        workerId,
+        status: 'idle',
+        tasksCompleted: 0,
+        tasksFailed: 0,
+        avgLatencyMs: 0,
+        lastActiveAt: Date.now(),
+        cpuLoad: 0,
+      },
+    };
+
+    worker.onmessage = (event) => this.handleWorkerMessage(workerId, event);
+    worker.onerror = (error) => this.handleWorkerError(workerId, error);
+
+    this.workers.set(workerId, entry);
+    return workerId;
+  }
+
+  private handleWorkerMessage(workerId: string, event: MessageEvent): void {
+    const { taskId, result, error, type } = event.data;
+    const entry = this.workers.get(workerId);
+    if (!entry) return;
+
+    if (type === 'metrics') {
+      entry.metrics.cpuLoad = event.data.cpuLoad ?? 0;
+      return;
+    }
+
+    const task = this.pendingTasks.get(taskId);
+    if (!task) return;
+
+    const latency = Date.now() - task.timestamp;
+    entry.latencyHistory.push(latency);
+    if (entry.latencyHistory.length > 50) entry.latencyHistory.shift();
+
+    entry.metrics.avgLatencyMs =
+      entry.latencyHistory.reduce((a, b) => a + b, 0) / entry.latencyHistory.length;
+    entry.metrics.lastActiveAt = Date.now();
+
+    if (error) {
+      entry.metrics.tasksFailed++;
+      task.reject(new Error(error));
+    } else {
+      entry.metrics.tasksCompleted++;
+      this.throughputWindow.push(Date.now());
+      task.resolve(result);
+    }
+
+    this.pendingTasks.delete(taskId);
+    entry.status = 'idle';
+    entry.metrics.status = 'idle';
+    entry.currentTaskId = null;
+
+    this.emitMetrics();
+    this.drainQueue();
+  }
+
+  private handleWorkerError(workerId: string, error: ErrorEvent): void {
+    const entry = this.workers.get(workerId);
+    if (!entry) return;
+
+    entry.status = 'error';
+    entry.metrics.status = 'error';
+
+    if (entry.currentTaskId) {
+      const task = this.pendingTasks.get(entry.currentTaskId);
+      if (task) {
+        task.reject(new Error(error.message));
+        this.pendingTasks.delete(entry.currentTaskId);
+      }
+    }
+
+    // Respawn worker
+    entry.worker.terminate();
+    this.workers.delete(workerId);
+    this.spawnWorker();
+    this.drainQueue();
+  }
+
+  private getIdleWorker(): WorkerEntry | null {
+    for (const [, entry] of Array.from(this.workers.entries())) {
+      if (entry.status === 'idle') return entry;
+    }
+    return null;
+  }
+
+  private drainQueue(): void {
+    if (this.taskQueue.length === 0) return;
+
+    // Sort by priority weight descending
+    this.taskQueue.sort(
+      (a, b) => PRIORITY_WEIGHTS[b.priority] - PRIORITY_WEIGHTS[a.priority]
+    );
+
+    let idleWorker = this.getIdleWorker();
+
+    // Scale up if needed and under cap
+    if (!idleWorker && this.workers.size < this.maxWorkers) {
+      const newId = this.spawnWorker();
+      idleWorker = this.workers.get(newId) ?? null;
+    }
+
+    if (!idleWorker) return;
+
+    const task = this.taskQueue.shift()!;
+    this.dispatchToWorker(idleWorker, task);
+  }
+
+  private dispatchToWorker(entry: WorkerEntry, task: WorkerTask): void {
+    entry.status = 'busy';
+    entry.metrics.status = 'busy';
+    entry.currentTaskId = task.id;
+    this.pendingTasks.set(task.id, task);
+
+    entry.worker.postMessage({
+      taskId: task.id,
+      type: task.type,
+      payload: task.payload,
+    });
+
+    if (task.timeoutMs) {
+      setTimeout(() => {
+        if (this.pendingTasks.has(task.id)) {
+          task.reject(new Error(`Task ${task.id} timed out after ${task.timeoutMs}ms`));
+          this.pendingTasks.delete(task.id);
+        }
+      }, task.timeoutMs);
+    }
+  }
+
+  /** Submit a task to the pool, returns a Promise */
+  submit<T = unknown, R = unknown>(
+    type: string,
+    payload: T,
+    options: { priority?: TaskPriority; timeoutMs?: number } = {}
+  ): Promise<R> {
+    return new Promise<R>((resolve, reject) => {
+      const task: WorkerTask<T, R> = {
+        id: `task-${++this.taskCounter}-${Date.now()}`,
+        type,
+        payload,
+        priority: options.priority ?? 'normal',
+        timestamp: Date.now(),
+        timeoutMs: options.timeoutMs,
+        resolve,
+        reject,
+      };
+
+      const idleWorker = this.getIdleWorker();
+      if (idleWorker) {
+        this.dispatchToWorker(idleWorker, task as WorkerTask);
+      } else {
+        this.taskQueue.push(task as WorkerTask);
+        // Scale up if under cap
+        if (this.workers.size < this.maxWorkers) {
+          this.spawnWorker();
+          this.drainQueue();
+        }
+      }
+    });
+  }
+
+  /** Get current pool metrics */
+  getMetrics(): PoolMetrics {
+    const now = Date.now();
+    // Clean throughput window to last 1 second
+    this.throughputWindow = this.throughputWindow.filter((t) => now - t < 1000);
+
+    const allLatencies = Array.from(this.workers.values() as Iterable<WorkerEntry>).flatMap(
+      (e) => e.latencyHistory
+    );
+    const avgLatency =
+      allLatencies.length > 0
+        ? allLatencies.reduce((a, b) => a + b, 0) / allLatencies.length
+        : 0;
+
+    const totalCompleted = Array.from(this.workers.values() as Iterable<WorkerEntry>).reduce(
+      (sum, e) => sum + e.metrics.tasksCompleted,
+      0
+    );
+
+    return {
+      totalWorkers: this.workers.size,
+      idleWorkers: Array.from(this.workers.values() as Iterable<WorkerEntry>).filter((e) => e.status === 'idle').length,
+      busyWorkers: Array.from(this.workers.values() as Iterable<WorkerEntry>).filter((e) => e.status === 'busy').length,
+      queueDepth: this.taskQueue.length,
+      throughputPerSec: this.throughputWindow.length,
+      avgLatencyMs: Math.round(avgLatency * 10) / 10,
+      totalTasksCompleted: totalCompleted,
+    };
+  }
+
+  getWorkerMetrics(): WorkerMetrics[] {
+    return Array.from(this.workers.values() as Iterable<WorkerEntry>).map((e) => ({ ...e.metrics }));
+  }
+
+  onMetrics(event: string, cb: (metrics: PoolMetrics) => void): () => void {
+    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
+    this.listeners.get(event)!.add(cb);
+    return () => this.listeners.get(event)?.delete(cb);
+  }
+
+  private emitMetrics(): void {
+    const metrics = this.getMetrics();
+    this.listeners.get('metrics')?.forEach((cb) => cb(metrics));
+  }
+
+  terminate(): void {
+    for (const [, entry] of Array.from(this.workers.entries())) {
+      entry.worker.terminate();
+    }
+    this.workers.clear();
+    this.taskQueue.length = 0;
+    this.pendingTasks.clear();
+  }
+}