enigma-memory 0.1.18 → 0.1.22

package/apps/desktop/src/server.mjs

@@ -0,0 +1,2914 @@
+// Enigma Sovereign Terminal Desktop Server Module
+// Reusable server library for enigma-desktop CLI bin, scripts, and programmatic hosts.
+// Implements strict host/origin validation (exact 127.0.0.1 or localhost + bound port) to defeat DNS rebinding.
+
+import http from 'node:http';
+import { createRequire } from 'node:module';
+import { ENIGMA_VERSION } from '../../../packages/core/src/version.mjs';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { TerminalSession } from '../../../packages/terminal-console/commands.mjs';
+import { PhantomBrowserBridge, OFFICIAL_TOKEN_CA, SOLANA_MAINNET_RPC } from '../../../packages/terminal-console/phantom-bridge.mjs';
+import { fetchSolanaStreamMetrics } from '../../../packages/terminal-console/solana-rpc.mjs';
+import { AutoAnchorEngine } from '../../../packages/terminal-console/auto-anchor.mjs';
+import { createSolanaProofMemoRef } from '../../../packages/terminal-console/solana-transport.mjs';
+import { createProofNetworkAnchorBatch } from '../../../packages/proof-network/src/index.js';
+import { normalizeSolanaLocalArtifact } from '../../cli/bin/enigma.mjs';
+import { createZkRuntime, defaultZkStatePath, ZK_HONESTY_NOTE } from './zk-state.mjs';
+import { EncryptedVectorStore } from '../../../packages/rag/src/index.js';
+import { computeHidingCommitment, deriveKeysFromPassphrase, PBKDF2_KDF_SPEC } from '../../../packages/vault/src/index.js';
+import { Enigma } from '../../../packages/sdk/src/index.js';
+import { GhostMeshFederationBridge } from '../../../packages/sdk/src/federation/index.js';
+import {
+  WebSocketTransport as FederationWebSocketTransport,
+  deriveDestination,
+  generateMeshIdentity,
+} from '../../../packages/mesh/src/index.js';
+import { createEnvironmentPlatformRuntime } from '../../../packages/inference-runtime/src/platform.js';
+import { createInferenceHttpHandler } from '../../../packages/inference-runtime/src/http.js';
+import { apiKeyFromAuthorization, createApiKeyService, createEphemeralApiKeyStore, createFileApiKeyStore } from '../../../packages/developer-platform/src/access-credentials.js';
+import { createApiKeyHttpHandler } from '../../../packages/developer-platform/src/http.js';
+import { createEphemeralUsageStore, createFileUsageStore, createUsageService } from '../../../packages/developer-platform/src/usage.js';
+import { createUsageHttpHandler } from '../../../packages/developer-platform/src/usage-http.js';
+import { createEphemeralCreditsStore, createFileCreditsStore, createPrivateCreditsService } from '../../../packages/private-economy/src/credits.js';
+import { createPrivateCreditsHttpHandler } from '../../../packages/private-economy/src/credits-http.js';
+import { createCreditPaymentService, createEphemeralPaymentStore, createFilePaymentStore, createSolanaPaymentVerifier, createStripeSubscriptionProvider } from '../../../packages/private-economy/src/payments.js';
+import { createPaymentHttpHandler } from '../../../packages/private-economy/src/payments-http.js';
+import { createX402FacilitatorClient, createX402ResourceHandler } from '../../../packages/private-economy/src/x402.js';
+const DESKTOP_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+export function getDefaultBundlePath() {
+  if (process.env.ENIGMA_BUNDLE_PATH) {
+    return path.resolve(process.env.ENIGMA_BUNDLE_PATH);
+  }
+  return path.resolve(process.cwd(), '.enigma', 'bundle.json');
+}
+const MAX_BODY_BYTES = 64 * 1024; // 64 KB limit
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+};
+
+class MemoryCaptureStream {
+  constructor() {
+    this.buffer = '';
+  }
+  write(chunk) {
+    this.buffer += String(chunk);
+    return true;
+  }
+  clear() {
+    this.buffer = '';
+  }
+}
+
+export class DesktopOperationalError extends Error {
+  constructor(code, message, statusCode = 400) {
+    super(message);
+    this.name = 'DesktopOperationalError';
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+function adapterEntries(options = {}) {
+  const configured = options.modelAdapters
+    ?? options.providerAdapters
+    ?? options.agentAdapters
+    ?? options.adapters
+    ?? options.connectors
+    ?? [];
+  if (configured instanceof Map) return [...configured.entries()];
+  if (Array.isArray(configured)) return configured.map((adapter) => [adapter?.id, adapter]);
+  if (configured && typeof configured === 'object') return Object.entries(configured);
+  throw new TypeError('Desktop model adapters must be an array, object, or Map');
+}
+const DESKTOP_CONTEXT_CARRIER_NAMES = new Set(['text', 'bitmap-png']);
+const DESKTOP_CONTEXT_CARRIER_REQUEST_MODES = new Set(['text', 'bitmap-png', 'auto']);
+
+function normalizeCarrierNames(value) {
+  let names;
+  if (Array.isArray(value) || value instanceof Set) {
+    names = [...value];
+  } else if (typeof value === 'string') {
+    names = [value];
+  } else if (value && typeof value === 'object') {
+    const declared = value.supported ?? value.carriers ?? value.modes;
+    if (Array.isArray(declared) || declared instanceof Set) {
+      names = [...declared];
+    } else if (typeof declared === 'string') {
+      names = [declared];
+    } else {
+      names = [...DESKTOP_CONTEXT_CARRIER_NAMES].filter((name) => value[name] === true);
+      if (value.vision === true) names.push('bitmap-png');
+    }
+  } else {
+    names = [];
+  }
+  const normalized = [...new Set(['text', ...names.map((name) => String(name).trim())])];
+  const unsupported = normalized.find((name) => !DESKTOP_CONTEXT_CARRIER_NAMES.has(name));
+  if (unsupported) {
+    throw new TypeError(`Unsupported desktop context carrier capability: ${unsupported}`);
+  }
+  return Object.freeze(normalized);
+}
+
+function normalizeContextCarriersByModel(adapter, models) {
+  const configured = adapter.contextCarriersByModel;
+  const entries = configured instanceof Map
+    ? [...configured.entries()]
+    : (configured && typeof configured === 'object' ? Object.entries(configured) : []);
+  const declared = new Map(entries.map(([model, names]) => [String(model).trim(), names]));
+  for (const model of declared.keys()) {
+    if (!models.includes(model)) {
+      throw new TypeError(`Desktop context carrier capability references unconfigured model: ${model}`);
+    }
+  }
+  const normalized = {};
+  for (const model of models) {
+    normalized[model] = normalizeCarrierNames(declared.get(model));
+  }
+  return Object.freeze(normalized);
+}
+
+function resolveDesktopContextCarrierRequest(payload, adapter, model) {
+  const requested = payload.contextCarrier;
+  if (!requested || typeof requested !== 'object' || Array.isArray(requested)) return null;
+  const mode = requested.mode === undefined ? 'text' : String(requested.mode);
+  if (!DESKTOP_CONTEXT_CARRIER_REQUEST_MODES.has(mode)) {
+    throw new DesktopOperationalError(
+      'CONTEXT_CARRIER_MODE_INVALID',
+      'contextCarrier.mode must be "text", "bitmap-png", or "auto"',
+      400
+    );
+  }
+  const supported = adapter.contextCarriersByModel[model] || Object.freeze(['text']);
+  return {
+    mode,
+    provider: adapter.provider,
+    model,
+    vision: supported.includes('bitmap-png'),
+    costs: requested.costs ?? requested.costPolicy ?? requested.costAssumptions,
+    expectedReuse: requested.expectedReuse,
+    tokenEstimates: requested.tokenEstimates,
+    limits: requested.limits ?? requested.renderLimits,
+    tabWidth: requested.tabWidth,
+    collapseRepeatedLines: requested.collapseRepeatedLines,
+    repetition: requested.repetition,
+  };
+}
+
+function sanitizeDesktopAdapterResult(value, key = '', seen = new WeakSet()) {
+  if (typeof value === 'string') {
+    return value.startsWith('data:image/png;base64,') ? '' : value;
+  }
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return { omittedBinaryBytes: value.byteLength };
+  }
+  if (!value || typeof value !== 'object') return value;
+  if (seen.has(value)) return '[circular]';
+  seen.add(value);
+  if (
+    key === 'contextCarrier'
+    || (
+      typeof value.selected === 'string'
+      && typeof value.textFallback === 'string'
+      && Array.isArray(value.blocks)
+      && value.descriptor
+      && value.decision
+    )
+  ) {
+    return {
+      descriptor: value.descriptor,
+      decision: value.decision,
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeDesktopAdapterResult(entry, '', seen));
+  }
+  if (
+    value?.source?.type === 'base64'
+    || value?.inlineData?.mimeType === 'image/png'
+    || value?.type === 'input_image'
+  ) {
+    return { omittedCarrierImage: true };
+  }
+  const sanitized = {};
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    sanitized[entryKey] = sanitizeDesktopAdapterResult(entryValue, entryKey, seen);
+  }
+  return sanitized;
+}
+
+const DESKTOP_PRIVACY_MODES = new Set(['off', 'anchor-guard']);
+const DESKTOP_ANCHOR_GUARD_PATTERNS = Object.freeze([
+  {
+    category: 'email',
+    expression: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi,
+  },
+  {
+    category: 'evm_wallet',
+    expression: /\b0x[a-fA-F0-9]{40}\b/g,
+  },
+  {
+    category: 'ipv4',
+    expression: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+    valid: (value) => value.split('.').every((part) => Number(part) <= 255),
+  },
+  {
+    category: 'phone',
+    expression: /(?:\+\d{1,3}[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]\d{3}[\s.-]\d{4}\b/g,
+  },
+  {
+    category: 'base58_wallet',
+    expression: /\b[1-9A-HJ-NP-Za-km-z]{32,44}\b/g,
+  },
+]);
+
+function resolveDesktopPrivacyMode(payload) {
+  const requested = payload.privacy;
+  if (requested === undefined || requested === null) return 'off';
+  const mode = typeof requested === 'string' ? requested : requested?.mode;
+  if (!DESKTOP_PRIVACY_MODES.has(mode)) {
+    throw new DesktopOperationalError(
+      'PRIVACY_MODE_INVALID',
+      'privacy.mode must be "off" or "anchor-guard"',
+      400
+    );
+  }
+  return mode;
+}
+
+function createDesktopAnchorGuard(mode) {
+  const replacements = [];
+  const tokensByValue = new Map();
+
+  function tokenFor(value, category) {
+    const prior = tokensByValue.get(value);
+    if (prior) return prior;
+    const token = `{{ENIGMA_${category.toUpperCase()}_${replacements.length + 1}}}`;
+    tokensByValue.set(value, token);
+    replacements.push({ category, token, value });
+    return token;
+  }
+
+  function redactText(value) {
+    if (mode === 'off' || typeof value !== 'string' || value.length === 0) return value;
+    let protectedText = value;
+    for (const pattern of DESKTOP_ANCHOR_GUARD_PATTERNS) {
+      protectedText = protectedText.replace(pattern.expression, (match) => {
+        if (pattern.valid && !pattern.valid(match)) return match;
+        return tokenFor(match, pattern.category);
+      });
+    }
+    return protectedText;
+  }
+
+  function transformStrings(value, transform, seen = new WeakMap()) {
+    if (typeof value === 'string') return transform(value);
+    if (!value || typeof value !== 'object' || Buffer.isBuffer(value) || value instanceof Uint8Array) {
+      return value;
+    }
+    if (seen.has(value)) return seen.get(value);
+    if (Array.isArray(value)) {
+      const transformed = [];
+      seen.set(value, transformed);
+      for (const entry of value) transformed.push(transformStrings(entry, transform, seen));
+      return transformed;
+    }
+    const transformed = {};
+    seen.set(value, transformed);
+    for (const [key, entry] of Object.entries(value)) {
+      transformed[key] = transformStrings(entry, transform, seen);
+    }
+    return transformed;
+  }
+
+  function redactValue(value) {
+    return transformStrings(value, redactText);
+  }
+
+  function restoreText(value) {
+    if (typeof value !== 'string' || replacements.length === 0) return value;
+    let restored = value;
+    for (const replacement of replacements) {
+      restored = restored.replaceAll(replacement.token, replacement.value);
+    }
+    return restored;
+  }
+
+  function restoreValue(value) {
+    return transformStrings(value, restoreText);
+  }
+
+  function report(invocation) {
+    if (mode === 'off') return null;
+    const categoryCounts = {};
+    for (const replacement of replacements) {
+      categoryCounts[replacement.category] = (categoryCounts[replacement.category] || 0) + 1;
+    }
+    const requestValue = String(invocation.prompt || '');
+    const retrievedValue = String(invocation.context || '');
+    const protectedInput = JSON.stringify({
+      schema: 'enigma.desktop.protected_adapter_input.v1',
+      requestValue,
+      retrievedValue,
+    });
+    const { commitment: protectedInputRef } = computeHidingCommitment(protectedInput);
+    return {
+      schema: 'enigma.desktop.anchor_guard_report.v1',
+      mode,
+      redactionCount: replacements.length,
+      categories: Object.fromEntries(Object.entries(categoryCounts).sort(([a], [b]) => a.localeCompare(b))),
+      protectedInputRef,
+      inputShape: {
+        requestChars: requestValue.length,
+        retrievedChars: retrievedValue.length,
+      },
+      limitations: [
+        'Pattern-based guard covers email, EVM wallet, IPv4, formatted phone, and base58 wallet anchors.',
+        'It does not identify arbitrary names, places, or sensitive prose.',
+        'Configured adapters control final transport; this unsigned operational report is not cryptographic proof.',
+      ],
+    };
+  }
+  return { redactValue, restoreValue, report };
+}
+
+
+export function createDesktopModelAdapterRegistry(options = {}) {
+  const registry = new Map();
+  for (const [configuredId, candidate] of adapterEntries(options)) {
+    const adapter = typeof candidate === 'function'
+      ? { id: configuredId, invoke: candidate }
+      : candidate;
+    if (!adapter || typeof adapter !== 'object' || typeof adapter.invoke !== 'function') continue;
+    const id = String(adapter.id ?? configuredId ?? '').trim();
+    const provider = String(adapter.provider ?? adapter.providerId ?? '').trim();
+    const models = Array.isArray(adapter.models)
+      ? adapter.models.map((model) => String(model).trim()).filter(Boolean)
+      : [String(adapter.model ?? '').trim()].filter(Boolean);
+    if (!id || !provider || models.length === 0) {
+      throw new TypeError('Each desktop model adapter requires id, provider, at least one model, and invoke()');
+    }
+    if (registry.has(id)) throw new TypeError(`Duplicate desktop model adapter id: ${id}`);
+    const uniqueModels = Object.freeze([...new Set(models)]);
+    registry.set(id, Object.freeze({
+      id,
+      provider,
+      models: uniqueModels,
+      contextCarriersByModel: normalizeContextCarriersByModel(adapter, uniqueModels),
+      invoke: adapter.invoke.bind(adapter),
+    }));
+  }
+  return registry;
+}
+
+export function resolveDesktopModelAdapter(registry, selection = {}) {
+  const provider = String(selection.provider ?? '').trim();
+  const model = String(selection.model ?? '').trim();
+  const adapterId = String(selection.adapterId ?? selection.adapter_id ?? '').trim();
+  const configured = [...registry.values()];
+  if (configured.length === 0) {
+    throw new DesktopOperationalError(
+      'MODEL_ADAPTER_NOT_CONFIGURED',
+      'No desktop model adapter is configured. Configure an authenticated provider connector in createDesktopServer({ modelAdapters }) and restart the desktop host.',
+      503
+    );
+  }
+  if (!provider || !model) {
+    throw new DesktopOperationalError(
+      'MODEL_SELECTION_REQUIRED',
+      'provider and model are required; select a configured desktop model adapter',
+      400
+    );
+  }
+  const adapter = configured.find((entry) =>
+    (!adapterId || entry.id === adapterId)
+    && entry.provider === provider
+    && entry.models.includes(model)
+  );
+  if (adapter) return adapter;
+  throw new DesktopOperationalError(
+    'MODEL_ADAPTER_NOT_CONFIGURED',
+    `No configured desktop model adapter matches provider "${provider}", model "${model}"${adapterId ? `, adapter "${adapterId}"` : ''}.`,
+    422
+  );
+}
+
+export function createDesktopServer(options = {}) {
+  let boundPort = options.port !== undefined ? options.port : 8765;
+  const host = '127.0.0.1';
+  let ephemeralTempDir = null;
+  let bundlePath;
+  if (options.inMemoryOnly === true) {
+    ephemeralTempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'enigma-ephemeral-sandbox-'));
+    bundlePath = options.bundlePath ? path.resolve(options.bundlePath) : path.join(ephemeralTempDir, 'bundle.json');
+  } else {
+    bundlePath = options.bundlePath ? path.resolve(options.bundlePath) : getDefaultBundlePath();
+  }
+  const authToken = options.authToken || crypto.randomBytes(32).toString('hex');
+  const oauthBearerAuthorizer = options.authorizeBearer || options.oauth?.authorizeBearer || null;
+  if (oauthBearerAuthorizer !== null && typeof oauthBearerAuthorizer !== 'function') {
+    throw new TypeError('authorizeBearer must be a function');
+  }
+  const apiKeyStore = options.apiKeyStore || (options.inMemoryOnly === true
+    ? createEphemeralApiKeyStore()
+    : createFileApiKeyStore({ path: options.apiKeyStorePath || path.join(path.dirname(bundlePath), 'api-keys.json') }));
+  const apiKeys = options.apiKeys || createApiKeyService({
+    store: apiKeyStore,
+    environment: options.apiKeyEnvironment || 'live',
+  });
+  const usageStore = options.usageStore || (options.inMemoryOnly === true
+    ? createEphemeralUsageStore()
+    : createFileUsageStore({ path: options.usageStorePath || path.join(path.dirname(bundlePath), 'usage.json') }));
+  const usage = options.usage || createUsageService({
+    store: usageStore,
+    pricing: options.usagePricing || {},
+    defaultPrincipal: { ownerId: 'local-owner', tenantId: 'local' },
+  });
+  const creditsStore = options.creditsStore || (options.inMemoryOnly === true
+    ? createEphemeralCreditsStore()
+    : createFileCreditsStore({ path: options.creditsStorePath || path.join(path.dirname(bundlePath), 'credits.json') }));
+  const credits = options.credits || createPrivateCreditsService({ store: creditsStore });
+  const recoveryAttempts = [];
+  const configuredPaymentPackages = options.paymentPackages || JSON.parse(process.env.ENIGMA_CREDIT_PACKAGES_JSON || '[]');
+  const usdcDestinationTokenAccount = options.usdcDestinationTokenAccount || process.env.ENIGMA_USDC_TREASURY_TOKEN_ACCOUNT || null;
+  const tokenBurnMint = options.tokenBurnMint || process.env.ENIGMA_CREDIT_BURN_MINT || null;
+  const verifySolanaPayment = options.verifySolanaPayment || ((usdcDestinationTokenAccount || tokenBurnMint)
+    ? createSolanaPaymentVerifier({ rpcUrl: options.solanaPaymentRpcUrl || process.env.ENIGMA_SOLANA_PAYMENT_RPC || SOLANA_MAINNET_RPC })
+    : null);
+  const stripeApiKey = process.env.ENIGMA_STRIPE_SECRET_KEY || null;
+  const stripeWebhookSecret = process.env.ENIGMA_STRIPE_WEBHOOK_SECRET || null;
+  if (!options.stripe && Boolean(stripeApiKey) !== Boolean(stripeWebhookSecret)) {
+    throw new Error('Stripe subscription rail requires both ENIGMA_STRIPE_SECRET_KEY and ENIGMA_STRIPE_WEBHOOK_SECRET');
+  }
+  const stripe = options.stripe || (stripeApiKey && stripeWebhookSecret
+    ? createStripeSubscriptionProvider({
+        apiKey: stripeApiKey,
+        webhookSecret: stripeWebhookSecret,
+        baseUrl: process.env.ENIGMA_STRIPE_API_BASE || undefined,
+      })
+    : null);
+  const paymentStore = options.paymentStore || (options.inMemoryOnly === true
+    ? createEphemeralPaymentStore()
+    : createFilePaymentStore({ path: options.paymentStorePath || path.join(path.dirname(bundlePath), 'payments.json') }));
+  const payments = options.payments || createCreditPaymentService({
+    store: paymentStore,
+    credits,
+    packages: configuredPaymentPackages,
+    usdcDestinationTokenAccount,
+    tokenBurnMint,
+    verifySolanaPayment,
+    stripe,
+  });
+  function localSessionPrincipal(req) {
+    const candidate = String(req.headers['x-enigma-auth-token'] || '');
+    const actual = Buffer.from(candidate);
+    const expected = Buffer.from(authToken);
+    if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) return null;
+    return { subject: 'local-owner', ownerId: 'local-owner', tenantId: 'local', scopes: apiKeys.supportedScopes, authentication: 'desktop_session' };
+  }
+  function requiredApiScopes(url) {
+    if (url.pathname.startsWith('/v1/images/')) return ['images:generate'];
+    if (url.pathname.startsWith('/v1/videos/')) return ['video:generate'];
+    if (url.pathname.startsWith('/v1/code/')) return ['code:execute'];
+    if (url.pathname.startsWith('/v1/browser/')) return ['browser:control'];
+    return ['models:invoke'];
+  }
+  async function authenticateApiRequest(req, requiredScopes) {
+    const local = localSessionPrincipal(req);
+    if (local) {
+      usage.setPrincipal(local);
+      req.enigmaPrincipal = local;
+      return local;
+    }
+    const rawApiKey = apiKeyFromAuthorization(req.headers.authorization);
+    let principal = rawApiKey ? await apiKeys.authenticate(rawApiKey, { requiredScopes }) : null;
+    if (!principal && oauthBearerAuthorizer) {
+      principal = await oauthBearerAuthorizer({
+        authorization: req.headers.authorization,
+        requiredScopes,
+        request: req,
+      });
+    }
+    if (principal) {
+      usage.setPrincipal(principal);
+      req.enigmaPrincipal = principal;
+    }
+    return principal;
+  }
+  const apiKeyHttp = createApiKeyHttpHandler({
+    apiKeys,
+    authorizeAdmin: async ({ request }) => localSessionPrincipal(request),
+  });
+  const usageHttp = createUsageHttpHandler({
+    usage,
+    authorize: async ({ request, requiredScopes }) => authenticateApiRequest(request, requiredScopes),
+  });
+  const creditsHttp = createPrivateCreditsHttpHandler({
+    credits,
+    authorizeCreation: async ({ request }) => Boolean(await authenticateApiRequest(request, ['credits:create'])),
+    admitRecovery: async ({ request }) => {
+      if (!await authenticateApiRequest(request, ['credits:create'])) return false;
+      const cutoff = Date.now() - 60_000;
+      while (recoveryAttempts.length && recoveryAttempts[0] < cutoff) recoveryAttempts.shift();
+      if (recoveryAttempts.length >= 5) return false;
+      recoveryAttempts.push(Date.now());
+      return true;
+    },
+  });
+  const paymentHttp = createPaymentHttpHandler({
+    payments,
+    stripe,
+    successUrl: () => `http://${host}:${boundPort}/?payment=success`,
+    cancelUrl: () => `http://${host}:${boundPort}/?payment=cancelled`,
+  });
+  const instanceId = crypto.randomUUID();
+
+  const phantomBridge = new PhantomBrowserBridge({
+    port: 0,
+    rpcUrl: SOLANA_MAINNET_RPC,
+  });
+
+  const autoAnchorEngine = new AutoAnchorEngine({
+    rootDir: path.dirname(bundlePath),
+    safeStorage: options.safeStorage,
+    cluster: 'mainnet-beta',
+  });
+  const stdoutCapture = new MemoryCaptureStream();
+  const stderrCapture = new MemoryCaptureStream();
+  
+  const vectorStoreDir = path.dirname(bundlePath);
+  const shouldPersistVectorStore = options.inMemoryOnly !== true && options.persistVectorStore !== false;
+  const shouldPersistSdkState = options.inMemoryOnly !== true && options.persistSdkState !== false;
+  const requiresPersistentKey = shouldPersistVectorStore || shouldPersistSdkState;
+  const vectorStorePath = options.vectorStorePath
+    ? path.resolve(options.vectorStorePath)
+    : path.join(vectorStoreDir, 'vector_store.enc.json');
+  const vectorStoreKeyPath = path.join(vectorStoreDir, 'vector_store.key.enc');
+
+  function getOrDeriveVectorMasterKey() {
+    if (options.vaultKey) {
+      return Buffer.isBuffer(options.vaultKey) ? options.vaultKey : Buffer.from(options.vaultKey, 'hex');
+    }
+    if (options.customKey || (options.zk && options.zk.customKey)) {
+      const k = String(options.customKey || options.zk.customKey);
+      return crypto.createHash('sha256').update(`enigma.custom_key.vector.${k}`).digest();
+    }
+    const passphraseInput = options.passphrase || process.env.ENIGMA_PASSPHRASE;
+    if (passphraseInput) {
+      const saltPath = path.join(vectorStoreDir, 'vector_store.kdf.json');
+      let salt;
+      if (fs.existsSync(saltPath)) {
+        try {
+          const kdfData = JSON.parse(fs.readFileSync(saltPath, 'utf8'));
+          salt = Buffer.from(kdfData.salt, 'base64');
+        } catch (e) {
+          salt = crypto.randomBytes(16);
+        }
+      } else {
+        salt = crypto.randomBytes(16);
+        fs.mkdirSync(vectorStoreDir, { recursive: true });
+        fs.writeFileSync(saltPath, JSON.stringify({ algorithm: 'pbkdf2', salt: salt.toString('base64'), iterations: PBKDF2_KDF_SPEC.iterations }), 'utf8');
+      }
+      return deriveKeysFromPassphrase(passphraseInput, salt, PBKDF2_KDF_SPEC).vaultKey;
+    }
+    if (options.safeStorage && typeof options.safeStorage.encryptString === 'function' && typeof options.safeStorage.decryptString === 'function') {
+      if (fs.existsSync(vectorStoreKeyPath)) {
+        const encData = JSON.parse(fs.readFileSync(vectorStoreKeyPath, 'utf8'));
+        if (encData.scheme !== 'enigma.safestorage.v1' || !encData.encryptedHex) {
+          throw new Error('Corrupted safeStorage vector key custody file');
+        }
+        const plainHex = options.safeStorage.decryptString(Buffer.from(encData.encryptedHex, 'hex'));
+        return Buffer.from(plainHex, 'hex');
+      } else {
+        const freshKey = crypto.randomBytes(32);
+        const encrypted = options.safeStorage.encryptString(freshKey.toString('hex'));
+        fs.mkdirSync(vectorStoreDir, { recursive: true });
+        fs.writeFileSync(vectorStoreKeyPath, JSON.stringify({
+          scheme: 'enigma.safestorage.v1',
+          encryptedHex: Buffer.from(encrypted).toString('hex'),
+          createdAt: Date.now(),
+        }, null, 2), 'utf8');
+        return freshKey;
+      }
+    }
+    if (options.allowHostBoundDemo === true || process.env.ENIGMA_ALLOW_HOSTBOUND === '1') {
+      const hostPayload = `${crypto.createHash('sha256').update(bundlePath).digest('hex')}:demo_host_key`;
+      return crypto.scryptSync(hostPayload, 'enigma.hostbound.vector.salt', 32);
+    }
+    if (!requiresPersistentKey) {
+      return crypto.randomBytes(32);
+    }
+    throw new Error(
+      'Vector store key custody not configured: provide safeStorage (Electron), a vaultKey, a passphrase (or ENIGMA_PASSPHRASE), or set allowHostBoundDemo:true for local CLI demos.'
+    );
+  }
+
+  let masterVectorKey = null;
+  if (requiresPersistentKey) {
+    masterVectorKey = getOrDeriveVectorMasterKey();
+  }
+
+  const ownsVectorStore = !options.vectorStore || options.ownVectorStore === true;
+  const ownsEmbeddingProvider = !options.embeddingProvider || options.ownEmbeddingProvider === true;
+  let vectorStore = options.vectorStore || new EncryptedVectorStore({
+    quantize: true,
+    ...(options.embeddingProvider ? { embeddingProvider: options.embeddingProvider } : {}),
+  });
+  if (shouldPersistVectorStore && fs.existsSync(vectorStorePath)) {
+    try {
+      const encryptedBundle = JSON.parse(fs.readFileSync(vectorStorePath, 'utf8'));
+      vectorStore = EncryptedVectorStore.decryptFromVault(encryptedBundle, masterVectorKey, {
+        ...(options.embeddingProvider || options.vectorStore?.embedder
+          ? { embeddingProvider: options.embeddingProvider || options.vectorStore.embedder }
+          : {}),
+      });
+    } catch (err) {
+      throw new Error(
+        `Failed to decrypt desktop vector store at "${vectorStorePath}": ${err.message}. `
+        + 'The existing encrypted file has been preserved intact. '
+        + 'Provide the original passphrase via ENIGMA_PASSPHRASE or use --passphrase-file to unlock.'
+      );
+    }
+  }
+
+  function persistVectorStore() {
+    if (!shouldPersistVectorStore || !vectorStorePath) return;
+    const bundle = vectorStore.encryptForVault(masterVectorKey);
+    fs.mkdirSync(path.dirname(vectorStorePath), { recursive: true });
+    const tmp = `${vectorStorePath}.tmp.${crypto.randomBytes(3).toString('hex')}`;
+    fs.writeFileSync(tmp, JSON.stringify(bundle, null, 2), 'utf8');
+    fs.renameSync(tmp, vectorStorePath);
+  }
+
+  const modelAdapters = createDesktopModelAdapterRegistry(options);
+  const platformRuntime = options.platformRuntime && typeof options.platformRuntime === 'object'
+    ? options.platformRuntime
+    : createEnvironmentPlatformRuntime({ usage });
+  const platformHttp = createInferenceHttpHandler({
+    ...platformRuntime,
+    authorize: async (req) => authenticateApiRequest(req, requiredApiScopes(new URL(req.url, `http://${host}:${boundPort}`))),
+  });
+  const x402Accepts = options.x402Accepts || (process.env.ENIGMA_X402_ACCEPTS_JSON ? JSON.parse(process.env.ENIGMA_X402_ACCEPTS_JSON) : null);
+  const x402ResourceBaseUrl = options.x402ResourceBaseUrl || process.env.ENIGMA_X402_RESOURCE_BASE_URL || null;
+  const x402Facilitator = options.x402Facilitator || (process.env.ENIGMA_X402_FACILITATOR_URL
+    ? createX402FacilitatorClient({
+        baseUrl: process.env.ENIGMA_X402_FACILITATOR_URL,
+        apiKey: process.env.ENIGMA_X402_FACILITATOR_API_KEY || null,
+      })
+    : null);
+  const x402ConfiguredParts = [x402Accepts, x402ResourceBaseUrl, x402Facilitator].filter(Boolean).length;
+  if (x402ConfiguredParts !== 0 && x402ConfiguredParts !== 3) {
+    throw new Error('x402 chat requires accepts, resource base URL, and facilitator configuration together');
+  }
+  const x402Http = x402ConfiguredParts === 3
+    ? createX402ResourceHandler({
+        facilitator: x402Facilitator,
+        routes: [{
+          method: 'POST',
+          path: '/v1/x402/chat/completions',
+          resource: {
+            url: new URL('/v1/x402/chat/completions', x402ResourceBaseUrl).toString(),
+            description: 'Enigma private-routing chat completion',
+            mimeType: 'application/json',
+            serviceName: 'Enigma',
+            tags: ['ai', 'privacy'],
+          },
+          accepts: x402Accepts,
+          execute: async ({ rawBody }) => {
+            if (!platformRuntime.chat) throw new Error('chat runtime is not configured');
+            let payload;
+            try { payload = JSON.parse(rawBody.toString('utf8') || '{}'); }
+            catch { throw new TypeError('x402 chat body must be valid JSON'); }
+            return { body: await platformRuntime.chat.complete(payload) };
+          },
+        }],
+      })
+    : async () => false;
+  const sdkOptions = options.sdk && typeof options.sdk === 'object' ? options.sdk : {};
+  const federationOptions = options.federation && typeof options.federation === 'object'
+    ? options.federation
+    : {};
+  const sdkScope = String(sdkOptions.scope || 'enigma.desktop').trim();
+  const sdkStoragePath = shouldPersistSdkState
+    ? path.resolve(sdkOptions.storagePath || path.join(vectorStoreDir, 'desktop_agent_state.enc.json'))
+    : null;
+  const operationalStatePath = shouldPersistSdkState
+    ? path.resolve(sdkOptions.operationalStatePath || path.join(vectorStoreDir, 'desktop_sdk_runtime.enc.json'))
+    : null;
+  const sdkVaultKey = masterVectorKey
+    ? Buffer.from(crypto.hkdfSync(
+        'sha256',
+        masterVectorKey,
+        Buffer.from('enigma.desktop.sdk.salt.v1', 'utf8'),
+        Buffer.from('enigma.desktop.sdk.v1', 'utf8'),
+        32
+      ))
+    : crypto.randomBytes(32);
+  const operationalKey = Buffer.from(crypto.hkdfSync(
+    'sha256',
+    sdkVaultKey,
+    Buffer.from('enigma.desktop.operational.salt.v1', 'utf8'),
+    Buffer.from('enigma.desktop.operational.v1', 'utf8'),
+    32
+  ));
+  const operationalAad = Buffer.from('enigma.desktop.sdk_runtime.v1', 'utf8');
+  let operationalState = null;
+  let sdkPromise = null;
+  let federationBridgePromise = null;
+  let federationBridge = null;
+  let federationTransport = null;
+  let agentTurnQueue = Promise.resolve();
+  const federationEvents = [];
+
+  function serializeIdentity(identity) {
+    return {
+      scope: identity.scope,
+      publicKey: identity.publicKey.toString('base64'),
+      secretKey: identity.secretKey.toString('base64'),
+      encryptionPublicKey: identity.encryptionPublicKey.toString('base64'),
+      encryptionSecretKey: identity.encryptionSecretKey.toString('base64'),
+    };
+  }
+
+  function deserializeIdentity(value) {
+    if (!value || typeof value !== 'object') throw new Error('Desktop SDK identity state is missing');
+    const identity = {
+      scope: String(value.scope || ''),
+      publicKey: Buffer.from(value.publicKey || '', 'base64'),
+      secretKey: Buffer.from(value.secretKey || '', 'base64'),
+      encryptionPublicKey: Buffer.from(value.encryptionPublicKey || '', 'base64'),
+      encryptionSecretKey: Buffer.from(value.encryptionSecretKey || '', 'base64'),
+    };
+    for (const [name, key] of Object.entries(identity)) {
+      if (name !== 'scope' && key.length !== 32) {
+        throw new Error(`Desktop SDK identity ${name} must be exactly 32 bytes`);
+      }
+    }
+    if (identity.scope !== sdkScope) {
+      throw new Error(`Desktop SDK identity scope "${identity.scope}" does not match "${sdkScope}"`);
+    }
+    identity.destination = deriveDestination(
+      identity.publicKey,
+      identity.encryptionPublicKey,
+      identity.scope
+    );
+    identity.destinationHex = identity.destination.toString('hex');
+    return identity;
+  }
+
+  function readOperationalState() {
+    if (operationalState) return operationalState;
+    if (!operationalStatePath || !fs.existsSync(operationalStatePath)) {
+      operationalState = {
+        schema: 'enigma.desktop.sdk_runtime.v1',
+        identity: serializeIdentity(generateMeshIdentity(sdkScope)),
+        federation: null,
+      };
+      return operationalState;
+    }
+    try {
+      const envelope = JSON.parse(fs.readFileSync(operationalStatePath, 'utf8'));
+      if (envelope?.schema !== 'enigma.desktop.encrypted_sdk_runtime.v1') {
+        throw new Error('unsupported encrypted runtime schema');
+      }
+      const decipher = crypto.createDecipheriv(
+        'aes-256-gcm',
+        operationalKey,
+        Buffer.from(envelope.iv, 'base64')
+      );
+      decipher.setAAD(operationalAad);
+      decipher.setAuthTag(Buffer.from(envelope.authTag, 'base64'));
+      const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
+        decipher.final(),
+      ]);
+      const value = JSON.parse(plaintext.toString('utf8'));
+      if (value?.schema !== 'enigma.desktop.sdk_runtime.v1') {
+        throw new Error('invalid decrypted runtime schema');
+      }
+      deserializeIdentity(value.identity);
+      operationalState = value;
+      return operationalState;
+    } catch (error) {
+      throw new Error(
+        `Failed to decrypt desktop SDK runtime at "${operationalStatePath}": ${error.message}. `
+        + 'The encrypted file has been preserved; restore the original desktop key custody.'
+      );
+    }
+  }
+
+  function persistOperationalState() {
+    if (!operationalStatePath) return;
+    const state = readOperationalState();
+    if (federationBridge) state.federation = federationBridge.exportState();
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', operationalKey, iv);
+    cipher.setAAD(operationalAad);
+    const ciphertext = Buffer.concat([
+      cipher.update(Buffer.from(JSON.stringify(state), 'utf8')),
+      cipher.final(),
+    ]);
+    const envelope = {
+      schema: 'enigma.desktop.encrypted_sdk_runtime.v1',
+      iv: iv.toString('base64'),
+      authTag: cipher.getAuthTag().toString('base64'),
+      ciphertext: ciphertext.toString('base64'),
+    };
+    fs.mkdirSync(path.dirname(operationalStatePath), { recursive: true });
+    const temporaryPath = `${operationalStatePath}.tmp.${crypto.randomBytes(4).toString('hex')}`;
+    fs.writeFileSync(temporaryPath, JSON.stringify(envelope, null, 2), 'utf8');
+    fs.renameSync(temporaryPath, operationalStatePath);
+  }
+
+  function getSdk() {
+    if (!sdkPromise) {
+      const pending = (async () => {
+        const identity = deserializeIdentity(readOperationalState().identity);
+        const connectOptions = {
+          agentId: sdkOptions.agentId || 'enigma-desktop',
+          scope: sdkScope,
+          storagePath: sdkStoragePath,
+          vaultKey: sdkVaultKey,
+          identity,
+          ...(sdkOptions.ragClient ? { ragClient: sdkOptions.ragClient } : {}),
+          ...(sdkOptions.ownRagClient === true ? { ownRagClient: true } : {}),
+        };
+        const instance = sdkOptions.enigmaFactory
+          ? await sdkOptions.enigmaFactory(connectOptions)
+          : await Enigma.connect(connectOptions);
+        persistOperationalState();
+        return instance;
+      })();
+      sdkPromise = pending;
+      pending.catch(() => {
+        if (sdkPromise === pending) sdkPromise = null;
+      });
+    }
+    return sdkPromise;
+  }
+
+  function configuredFederationPeers() {
+    const configured = federationOptions.registeredPeers ?? federationOptions.peerDescriptors ?? [];
+    if (configured instanceof Map) return [...configured.entries()];
+    if (Array.isArray(configured)) {
+      return configured.map((peer) => [peer?.peerId ?? peer?.peer_id, peer]);
+    }
+    if (configured && typeof configured === 'object') return Object.entries(configured);
+    throw new TypeError('federation registeredPeers must be an array, object, or Map');
+  }
+
+  function recordFederationEvent(kind, event) {
+    federationEvents.push({
+      kind,
+      at: new Date().toISOString(),
+      packetId: event?.packet_id ?? event?.packetId ?? null,
+      peerId: event?.fromPeerId ?? null,
+    });
+    if (federationEvents.length > 25) federationEvents.splice(0, federationEvents.length - 25);
+    persistOperationalState();
+  }
+
+  async function getFederationBridge() {
+    if (!federationBridgePromise) {
+      const pending = (async () => {
+        const enigma = await getSdk();
+        federationTransport = federationOptions.transport || new FederationWebSocketTransport({
+          id: federationOptions.transportId || 'desktop-federation-ws',
+          host: '127.0.0.1',
+          port: federationOptions.port ?? 0,
+          peers: federationOptions.peerAddresses || [],
+        });
+        const bridge = new GhostMeshFederationBridge({
+          enigma,
+          transport: federationTransport,
+          scope: sdkScope,
+          manageTransport: federationOptions.manageTransport !== false,
+          requestTimeoutMs: federationOptions.requestTimeoutMs,
+          state: readOperationalState().federation || undefined,
+        });
+        for (const [peerId, peer] of configuredFederationPeers()) {
+          bridge.registerPeer(peerId, peer);
+        }
+        bridge.on('grant', (event) => recordFederationEvent('grant', event));
+        bridge.on('query', (event) => recordFederationEvent('query', event));
+        bridge.on('response', (event) => recordFederationEvent('response', event));
+        bridge.on('revocation', (event) => recordFederationEvent('revocation', event));
+        bridge.on('rejected', (event) => recordFederationEvent('rejected', event));
+        federationBridge = bridge;
+        return bridge;
+      })();
+      federationBridgePromise = pending;
+      pending.catch(() => {
+        if (federationBridgePromise === pending) federationBridgePromise = null;
+      });
+    }
+    return federationBridgePromise;
+  }
+
+  function federationStatus(bridge) {
+    const endpoint = bridge.localEndpoint;
+    const transport = typeof federationTransport?.getStats === 'function'
+      ? federationTransport.getStats()
+      : {
+          id: federationTransport?.id || null,
+          running: Boolean(federationTransport?.running),
+        };
+    return {
+      ok: true,
+      schema: 'enigma.desktop.federation_status.v1',
+      started: bridge.started,
+      scope: bridge.scope,
+      endpoint: {
+        destinationHex: endpoint.destinationHex
+          || deriveDestination(endpoint.publicKey, endpoint.encryptionPublicKey, bridge.scope).toString('hex'),
+        publicKeyHex: Buffer.from(endpoint.publicKey).toString('hex'),
+        encryptionPublicKeyHex: Buffer.from(endpoint.encryptionPublicKey).toString('hex'),
+      },
+      transport,
+      registeredPeers: [...bridge.peers.values()].map((peer) => ({
+        peerId: peer.peerId,
+        scope: peer.scope,
+        destinationHex: peer.destination.toString('hex'),
+        publicKeyHex: peer.publicKey.toString('hex'),
+        encryptionPublicKeyHex: peer.encryptionPublicKey.toString('hex'),
+      })),
+      activeGrantIds: [...bridge.knownGrants.keys()],
+      pendingQueries: bridge.pendingQueries.size,
+      recentEvents: federationEvents.slice().reverse(),
+      persisted: Boolean(operationalStatePath),
+    };
+  }
+
+  function enqueueAgentTurn(action) {
+    const pending = agentTurnQueue.then(action);
+    agentTurnQueue = pending.catch(() => {});
+    return pending;
+  }
+
+  const session = new TerminalSession({
+    bundlePath,
+    io: {
+      stdin: process.stdin,
+      stdout: stdoutCapture,
+      stderr: stderrCapture,
+    },
+  });
+
+  session.phantomBridge = phantomBridge;
+  phantomBridge.onWalletConnected = (wallet) => {
+    session.connectedWallet = wallet;
+  };
+  session.autoAnchorEngine = autoAnchorEngine;
+
+  let executeQueue = Promise.resolve();
+  let zkRuntimePromise = null;
+  let zkActionQueue = Promise.resolve();
+
+  function getZkRuntime() {
+    if (!zkRuntimePromise) {
+      const zkOptions = options.zk && typeof options.zk === 'object' ? options.zk : {};
+      const pending = createZkRuntime({
+        ...zkOptions,
+        safeStorage: zkOptions.safeStorage ?? options.safeStorage,
+        statePath: zkOptions.statePath || defaultZkStatePath(bundlePath),
+      });
+      zkRuntimePromise = pending;
+      pending.catch(() => {
+        if (zkRuntimePromise === pending) zkRuntimePromise = null;
+      });
+    }
+    return zkRuntimePromise;
+  }
+
+  function enqueueZkAction(action) {
+    const pending = zkActionQueue.then(action);
+    zkActionQueue = pending.catch(() => {});
+    return pending;
+  }
+  // --- GhostMesh P2P Mesh Subsystem -----------------------------------------
+  let meshNode = null;
+  const meshInbox = [];
+  const meshSaleOffers = [];
+  const meshZkProofs = [];
+
+  async function getMeshNode() {
+    if (!meshNode) {
+      const meshOpts = options.mesh && typeof options.mesh === 'object' ? options.mesh : {};
+      const { MeshGossipNode, WebSocketTransport } = await import('../../../packages/mesh/src/index.js');
+      meshNode = new MeshGossipNode({
+        scope: meshOpts.scope || 'enigma.memory',
+        nodeId: meshOpts.nodeId,
+      });
+      if (meshOpts.port !== undefined && meshOpts.port !== null) {
+        const wsTransport = new WebSocketTransport({
+          port: meshOpts.port,
+          peers: meshOpts.peers || [],
+        });
+        meshNode.addTransport(wsTransport);
+      }
+      meshNode.on('capsule', (capsule) => {
+        meshInbox.push({ ...capsule, receivedAt: new Date().toISOString() });
+      });
+      meshNode.on('sale:offer', (offer) => {
+        meshSaleOffers.push({ ...offer, receivedAt: new Date().toISOString() });
+      });
+      meshNode.on('zk:proof', (proof) => {
+        meshZkProofs.push({ ...proof, receivedAt: new Date().toISOString() });
+      });
+      await meshNode.start();
+    }
+    return meshNode;
+  }
+  // --- Custody-local proving + opaque relayer sessions -----------------------
+  // Private proving inputs never enter the renderer. The custody runtime
+  // proves locally, stores the public proof beside a single-use opaque handle,
+  // and zeroizes private pending values after settlement, expiry, or eviction.
+  const FR_MODULUS = BigInt('0x30644e72e131a029b85045b68181585d2833e84879b9709143e1f593f0000001');
+  const PREPARE_TTL_MS = 10 * 60 * 1000;
+  const PREPARE_MAX_SESSIONS = 32;
+  const pendingPrepares = new Map();
+  const relayInFlight = new Set();
+  const scrubPrepareValue = (value) => {
+    if (!value || typeof value !== 'object') return;
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+      value.fill(0);
+      return;
+    }
+    for (const key of Object.keys(value)) {
+      const entry = value[key];
+      if (entry && typeof entry === 'object') scrubPrepareValue(entry);
+      else if (typeof entry === 'string') value[key] = '';
+      else if (typeof entry === 'bigint') value[key] = 0n;
+      else if (typeof entry === 'number') value[key] = 0;
+      else value[key] = null;
+    }
+  };
+  const clearPendingPrepare = (entry) => {
+    if (!entry) return;
+    scrubPrepareValue(entry.pending);
+    entry.pending = null;
+    entry.proofBytes = null;
+    entry.publicInputs = null;
+  };
+  // Witness material the relayer must NEVER receive; presence is a hard 400.
+  const RELAY_FORBIDDEN_FIELDS = [
+    'ownerKey', 'rho', 'payloadCommit', 'witness', 'witnessInput',
+    'noteOpenings', 'recipientSecretKeyB64', 'secretKey', 'plaintext',
+  ];
+  const PROVER_ASSET_ROUTE = {
+    'action_transition.wasm': { key: 'wasm', contentType: 'application/wasm' },
+    'action_transition.zkey': { key: 'zkey', contentType: 'application/octet-stream' },
+    'snarkjs.min.js': { key: 'snarkjs', contentType: 'text/javascript; charset=utf-8' },
+  };
+
+  async function proverAssetFiles(runtime) {
+    const zkOptions = options.zk && typeof options.zk === 'object' ? options.zk : {};
+    // wasm/zkey: via the checksum-pinned resolver when available (packaged
+    // installs lack circuits/build); injected-deps tests keep the fixture paths.
+    const assets = typeof runtime.getProvingAssetPaths === 'function'
+      ? await runtime.getProvingAssetPaths()
+      : runtime.artifactPaths;
+    let snarkjs = null;
+    if (zkOptions.snarkjsBundlePath) {
+      snarkjs = path.resolve(zkOptions.snarkjsBundlePath);
+    } else {
+      // snarkjs is a declared runtime dependency: resolve its package entry
+      // and take the sibling IIFE bundle (build/snarkjs.min.js).
+      try {
+        const req = createRequire(import.meta.url);
+        const main = req.resolve('snarkjs');
+        const candidate = path.join(path.dirname(main), 'snarkjs.min.js');
+        if (fs.existsSync(candidate)) snarkjs = candidate;
+      } catch { /* fall through to legacy walk */ }
+      if (!snarkjs) {
+        let dir = path.dirname(assets.zkey);
+        for (let i = 0; i < 4 && !snarkjs; i += 1) {
+          dir = path.dirname(dir);
+          const candidate = path.join(dir, 'node_modules', 'snarkjs', 'build', 'snarkjs.min.js');
+          if (fs.existsSync(candidate)) snarkjs = candidate;
+        }
+      }
+    }
+    return { wasm: assets.wasm, zkey: assets.zkey, snarkjs };
+  }
+
+  function validateRelayShape(proof, publicInputs, expectedInputCount) {
+    if (!proof || typeof proof !== 'object' || Array.isArray(proof)) {
+      return 'proof must be an object { a, b, c } of hex strings (64/128/64 bytes)';
+    }
+    const expectedHexLength = { a: 128, b: 256, c: 128 };
+    for (const [key, hexLength] of Object.entries(expectedHexLength)) {
+      const value = proof[key];
+      if (typeof value !== 'string' || !/^[0-9a-fA-F]+$/.test(value) || value.length !== hexLength) {
+        return `proof.${key} must be a ${hexLength}-character hex string (${hexLength / 2} bytes)`;
+      }
+    }
+    if (!Array.isArray(publicInputs) || publicInputs.length !== expectedInputCount) {
+      return `publicInputs must be an array of ${expectedInputCount} × 64-hex field elements`;
+    }
+    for (let i = 0; i < publicInputs.length; i += 1) {
+      const value = publicInputs[i];
+      if (typeof value !== 'string' || !/^[0-9a-fA-F]{64}$/.test(value)) {
+        return `publicInputs[${i}] must be a 64-character hex string`;
+      }
+      if (BigInt(`0x${value}`) >= FR_MODULUS) {
+        return `publicInputs[${i}] is not a canonical BN254 scalar field element`;
+      }
+    }
+    return null;
+  }
+
+
+  // --- Sealed Sale (ZKCP) marketplace helpers --------------------------------
+  // SOVEREIGNTY INVARIANT: no user secret (ownerKey/rho/DEK/buyerSecret/
+  // plaintext) may cross these endpoints. Proving happens in this process
+  // against the checksum-pinned sealed_sale_release artifacts; the wire
+  // carries only { proof bytes, 6 public inputs, pubkeys, terms } and public
+  // commitments/ciphertext. The envelope triple leaves custody only in claim.
+  const SALE_FORBIDDEN_FIELDS = [
+    'ownerKey', 'rho', 'dekLo', 'dekHi', 'buyerSecret', 'secretKey',
+    'recipientSecretKeyB64', 'noteOpenings', 'noteContext', 'witness',
+    'witnessInput', 'plaintext', 'esk', 'payloadCommit',
+    'epk', 'encDek', 'nonce', 'nonceHex',
+  ];
+  const saleForbiddenField = (payload) => {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return 'request body must be a JSON object';
+    for (const field of SALE_FORBIDDEN_FIELDS) {
+      if (field in payload) {
+        return `sale endpoints accept only proof/public-input/commitment material — secret field "${field}" must never be sent`;
+      }
+    }
+    return null;
+  };
+  const parseHex32 = (value, name) => {
+    if (typeof value !== 'string' || !/^[0-9a-fA-F]{64}$/.test(value)) {
+      return { error: `${name} must be a 64-character hex string (32 bytes)` };
+    }
+    return { bytes: Buffer.from(value, 'hex') };
+  };
+  const parseUint64 = (value, name) => {
+    if (typeof value !== 'string' && typeof value !== 'number') return { error: `${name} must be an integer (string or number)` };
+    if (!/^(0|[1-9][0-9]*)$/.test(String(value))) return { error: `${name} must be a non-negative integer` };
+    const parsed = BigInt(value);
+    if (parsed >= (1n << 64n)) return { error: `${name} is out of u64 range` };
+    return { value: parsed };
+  };
+  const parseCiphertextChunks = (value) => {
+    if (!Array.isArray(value) || value.length !== 32) {
+      return { error: 'ciphertextChunks must be an array of 32 decimal-string field elements' };
+    }
+    for (let i = 0; i < value.length; i += 1) {
+      const chunk = value[i];
+      if (typeof chunk !== 'string' || !/^(0|[1-9][0-9]*)$/.test(chunk)) {
+        return { error: `ciphertextChunks[${i}] must be a decimal string` };
+      }
+      if (BigInt(chunk) >= FR_MODULUS) {
+        return { error: `ciphertextChunks[${i}] is not a canonical BN254 scalar field element` };
+      }
+    }
+    return { chunks: value };
+  };
+  const parsePredecessorReceiptRefs = (value) => {
+    if (value === undefined) return { refs: [] };
+    if (!Array.isArray(value) || value.length > 16) {
+      return { error: 'predecessorReceiptRefs must be an array of at most 16 ZK settlement receipt refs' };
+    }
+    if (value.some((ref) => typeof ref !== 'string' || !/^zksettle_[a-f0-9]{64}$/.test(ref))) {
+      return { error: 'predecessorReceiptRefs contains an invalid ZK settlement receipt ref' };
+    }
+    return { refs: [...new Set(value)] };
+  };
+  
+  const SALE_ERROR_STATUS = {
+    ZK_UNAVAILABLE: 503,
+    BAD_REQUEST: 400,
+    VK_GATE_REJECTED: 409,
+    PROOF_STATE_MISMATCH: 409,
+    NOTE_OPENING_MISSING: 409,
+    NOTE_NOT_SALEABLE: 409,
+    BUYER_KEY_MISSING: 409,
+    SALE_ENVELOPE_MISSING: 409,
+    SALE_ENVELOPE_MISMATCH: 409,
+    SALE_NOT_CLAIMED: 409,
+    SALE_ALREADY_CLAIMED: 409,
+    SALE_TERMS_MISMATCH: 409,
+    SALE_TERMS_NOT_BUYER_BOUND: 409,
+    SALE_CIPHER_MISMATCH: 409,
+    SALE_RECEIPT_MISSING: 404,
+    SALE_OPEN_REJECTED: 422,
+  };
+  const saleErrorStatus = (err) => SALE_ERROR_STATUS[err.code]
+    ?? (err.name === 'ProvingAssetError' ? 501 : 500);
+  const receiptJson = (receipt) => ({
+    saleTermsHash: Buffer.from(receipt.saleTermsHash).toString('hex'),
+    keyCommit: Buffer.from(receipt.keyCommit).toString('hex'),
+    cipherCommit: Buffer.from(receipt.cipherCommit).toString('hex'),
+    envelopeCommit: Buffer.from(receipt.envelopeCommit).toString('hex'),
+    payloadCommitPos: Buffer.from(receipt.payloadCommitPos).toString('hex'),
+    epk: Buffer.from(receipt.epk).toString('hex'),
+    encDek: Buffer.from(receipt.encDek).toString('hex'),
+    nonce: Buffer.from(receipt.nonce).toString('hex'),
+    slot: receipt.slot,
+    claimed: !(receipt.epk.every((b) => b === 0) && receipt.encDek.every((b) => b === 0) && receipt.nonce.every((b) => b === 0)),
+  });
+
+  function writeJson(res, statusCode, value) {
+    res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(value));
+  }
+
+  function enqueueCommandExecution(commandLine) {
+    const executePromise = executeQueue.then(async () => {
+      stdoutCapture.clear();
+      stderrCapture.clear();
+      const exitCode = await session.executeCommand(commandLine);
+      const output = stdoutCapture.buffer + (stderrCapture.buffer ? '\n' + stderrCapture.buffer : '');
+      return {
+        ok: exitCode === 0 || exitCode === 'EXIT',
+        exitCode: exitCode === 'EXIT' ? 0 : (exitCode || 0),
+        output: output || '(no output)',
+        connectedWallet: session.connectedWallet || null,
+      };
+    });
+    executeQueue = executePromise.catch(() => {});
+    return executePromise;
+  }
+  function validateSecurityHeaders(req, res, { requireAuth = false } = {}) {
+    const rawHost = req.headers['host'];
+    if (!rawHost) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'host header required' }));
+      return false;
+    }
+
+    let parsedHost;
+    try {
+      parsedHost = new URL(`http://${rawHost}`);
+    } catch {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'malformed host header' }));
+      return false;
+    }
+
+    const hostName = parsedHost.hostname.toLowerCase();
+    const hostPort = Number(parsedHost.port || 80);
+    const validHostName = hostName === '127.0.0.1' || hostName === 'localhost';
+    const validHostPort = boundPort === 0 || hostPort === boundPort;
+
+    if (!validHostName || !validHostPort) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'host header rejected: must be exact 127.0.0.1 or localhost on bound port' }));
+      return false;
+    }
+
+    const rawOrigin = req.headers['origin'];
+    if (rawOrigin) {
+      let parsedOrigin;
+      try {
+        parsedOrigin = new URL(rawOrigin);
+      } catch {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'malformed origin header' }));
+        return false;
+      }
+
+      const originName = parsedOrigin.hostname.toLowerCase();
+      const originPort = Number(parsedOrigin.port || (parsedOrigin.protocol === 'https:' ? 443 : 80));
+      const validOriginName = originName === '127.0.0.1' || originName === 'localhost';
+      const validOriginPort = boundPort === 0 || originPort === boundPort;
+
+      if (!validOriginName || !validOriginPort) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'cross-origin request rejected' }));
+        return false;
+      }
+    }
+
+    if (requireAuth) {
+      const token = req.headers['x-enigma-auth-token'];
+      if (!token || token !== authToken) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'unauthorized or invalid session token' }));
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  function readBody(req, res, callback) {
+    let body = '';
+    let bytes = 0;
+    let rejected = false;
+
+    req.on('data', (chunk) => {
+      if (rejected) return;
+      bytes += chunk.length;
+      if (bytes > MAX_BODY_BYTES) {
+        rejected = true;
+        req.pause();
+        res.writeHead(413, {
+          'Content-Type': 'application/json',
+          'Connection': 'close',
+        });
+        res.end(JSON.stringify({ ok: false, error: 'payload too large' }));
+        req.resume();
+        return;
+      }
+      body += chunk;
+    });
+
+    req.on('end', () => {
+      if (!rejected) {
+        callback(body);
+      }
+    });
+  }
+
+  function writeOperationalError(res, error, fallbackCode, fallbackStatus = 500) {
+    const statusCode = error instanceof DesktopOperationalError
+      ? error.statusCode
+      : fallbackStatus;
+    writeJson(res, statusCode, {
+      ok: false,
+      error: {
+        code: error instanceof DesktopOperationalError ? error.code : fallbackCode,
+        message: error?.message || 'Desktop operational request failed',
+      },
+    });
+  }
+
+  const server = http.createServer(async (req, res) => {
+    // Apply host validation before serving any request (including static files/token)
+    if (!validateSecurityHeaders(req, res, { requireAuth: false })) return;
+
+    const url = new URL(req.url, `http://${host}:${boundPort}`);
+
+    const origin = req.headers['origin'];
+    if (origin) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+      res.setHeader('Access-Control-Expose-Headers', 'PAYMENT-REQUIRED, PAYMENT-RESPONSE');
+      res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-Enigma-Auth-Token, PAYMENT-SIGNATURE');
+    }
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    if (await apiKeyHttp(req, res)) return;
+    if (await creditsHttp(req, res)) return;
+    if (await paymentHttp(req, res)) return;
+    if (await x402Http(req, res, url)) return;
+    if (await usageHttp(req, res)) return;
+    if (await usage.run({ principal: null }, () => platformHttp.handle(req, res, url))) return;
+    if (url.pathname === '/api/health' && req.method === 'GET') {
+      writeJson(res, 200, {
+        ok: true,
+        schema: 'enigma.desktop.health.v1',
+        service: 'enigma-desktop',
+        version: ENIGMA_VERSION,
+        instanceId,
+        authRequired: true,
+      });
+      return;
+    }
+
+
+    if (url.pathname === '/api/agent/adapters' && req.method === 'GET') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      writeJson(res, 200, {
+        ok: true,
+        schema: 'enigma.desktop.model_adapters.v1',
+        configured: modelAdapters.size > 0,
+        adapters: [...modelAdapters.values()].map(({
+          id,
+          provider,
+          models,
+          contextCarriersByModel,
+        }) => ({
+          id,
+          provider,
+          models,
+          contextCarriersByModel,
+        })),
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/agent/turn' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeOperationalError(
+            res,
+            new DesktopOperationalError('INVALID_JSON', 'request body must be valid JSON', 400),
+            'AGENT_TURN_FAILED'
+          );
+          return;
+        }
+        try {
+          const prompt = typeof payload.prompt === 'string' ? payload.prompt.trim() : '';
+          if (!prompt) {
+            throw new DesktopOperationalError(
+              'AGENT_PROMPT_REQUIRED',
+              'prompt must be a non-empty string',
+              400
+            );
+          }
+          const adapter = resolveDesktopModelAdapter(modelAdapters, payload);
+          const selectedModel = String(payload.model).trim();
+          const contextCarrier = resolveDesktopContextCarrierRequest(payload, adapter, selectedModel);
+          const privacyMode = resolveDesktopPrivacyMode(payload);
+          if (privacyMode === 'anchor-guard' && contextCarrier && contextCarrier.mode !== 'text') {
+            throw new DesktopOperationalError(
+              'PRIVACY_CARRIER_UNSUPPORTED',
+              'Anchor Guard requires a text context carrier so protected anchors cannot be embedded in an image',
+              422
+            );
+          }
+          const anchorGuard = createDesktopAnchorGuard(privacyMode);
+          let privacyReport = null;
+          const enigma = await getSdk();
+          const turn = await enqueueAgentTurn(() => enigma.runAgentTurn({
+            prompt,
+            retrieval: payload.retrieval && typeof payload.retrieval === 'object'
+              ? payload.retrieval
+              : {},
+            rememberResponse: payload.rememberResponse !== false,
+            ...(contextCarrier ? { contextCarrier } : {}),
+            metadata: {
+              ...(payload.metadata && typeof payload.metadata === 'object' ? payload.metadata : {}),
+              desktopModel: {
+                adapterId: adapter.id,
+                provider: adapter.provider,
+                model: selectedModel,
+              },
+            },
+            invoke: async (invocation) => {
+              try {
+                const protectedInvocation = privacyMode === 'off'
+                  ? invocation
+                  : anchorGuard.redactValue(invocation);
+                privacyReport = anchorGuard.report(protectedInvocation);
+                const adapterResult = await adapter.invoke({
+                  ...protectedInvocation,
+                  adapterId: adapter.id,
+                  provider: adapter.provider,
+                  model: selectedModel,
+                });
+                const sanitizedResult = sanitizeDesktopAdapterResult(adapterResult);
+                return privacyMode === 'off'
+                  ? sanitizedResult
+                  : anchorGuard.restoreValue(sanitizedResult);
+              } catch (error) {
+                throw new DesktopOperationalError(
+                  'MODEL_ADAPTER_INVOCATION_FAILED',
+                  `Configured model adapter "${adapter.id}" failed: ${error.message}`,
+                  502
+                );
+              }
+            },
+          }));
+          const contextRefs = turn.context.items.map((item) => ({
+            memoryId: item.id,
+            commitment: item.commitment || null,
+            receiptRef: item.metadata?.agentTurn?.receiptRef
+              || item.metadata?.updateReceiptRef
+              || null,
+          }));
+          writeJson(res, 200, {
+            ok: true,
+            schema: 'enigma.desktop.agent_turn.v1',
+            adapter: {
+              id: adapter.id,
+              provider: adapter.provider,
+              model: selectedModel,
+            },
+            result: turn.result,
+            context: {
+              ...(turn.contextCarrier ? {} : { contextText: turn.context.contextText }),
+              refs: contextRefs,
+              estimatedTokens: turn.context.estimatedTokens,
+            },
+            memory: turn.memory
+              ? { id: turn.memory.id, scope: turn.memory.scope, type: turn.memory.type }
+              : null,
+            receiptRefs: turn.receipts.refs,
+            ...(turn.contextCarrier ? { contextCarrier: turn.contextCarrier } : {}),
+            ...(privacyReport ? { privacyReport } : {}),
+          });
+        } catch (error) {
+          writeOperationalError(res, error, 'AGENT_TURN_FAILED');
+        }
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/mesh/federation/status' && req.method === 'GET') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      try {
+        const bridge = await getFederationBridge();
+        writeJson(res, 200, federationStatus(bridge));
+      } catch (error) {
+        writeOperationalError(res, error, 'FEDERATION_BRIDGE_FAILED');
+      }
+      return;
+    }
+
+    if (url.pathname === '/api/mesh/federation/start' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      try {
+        const bridge = await getFederationBridge();
+        await bridge.start();
+        persistOperationalState();
+        writeJson(res, 200, federationStatus(bridge));
+      } catch (error) {
+        writeOperationalError(res, error, 'FEDERATION_BRIDGE_FAILED');
+      }
+      return;
+    }
+
+
+    // Real Command Execution API Endpoint
+    if ((url.pathname === '/api/exec' || url.pathname === '/api/terminal/exec') && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+
+      readBody(req, res, async (body) => {
+        try {
+          const payload = JSON.parse(body || '{}');
+          const commandLine = String(payload.command || '').trim();
+
+          if (!commandLine) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true, output: '', exitCode: 0 }));
+            return;
+          }
+
+          const result = await enqueueCommandExecution(commandLine);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(result));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err.message }));
+        }
+      });
+      return;
+    }
+
+    // ZK Proof Layer status. This endpoint is intentionally read-only and
+    // fail-closed: operational failures are always a 200 JSON shape with
+    // available=false, never an HTML error page.
+    if (url.pathname === '/api/zk/status' && req.method === 'GET') {
+      try {
+        const runtime = await getZkRuntime();
+        const result = await runtime.status();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, ...result }));
+      } catch (err) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          ok: true,
+          available: false,
+          reason: `ZK runtime initialization failed: ${err.message}`,
+          cluster: options.zk?.cluster || 'localnet',
+          sharedStatePda: null,
+          programId: null,
+          noteRoot: null,
+          nullRoot: null,
+          noteCount: null,
+          nullCount: null,
+          localNoteCount: null,
+          localNullCount: null,
+          provingArtifacts: false,
+          honesty: ZK_HONESTY_NOTE,
+        }));
+      }
+      return;
+    }
+
+    // The prove + settle flow blocks honestly for the full local proof
+    // (normally ~2s) and confirmed Solana transaction. Actions are serialized
+    // so two requests can never mutate the same local tree snapshot.
+    if (url.pathname === '/api/zk/append' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'request body must be valid JSON' }));
+          return;
+        }
+        const plaintext = typeof payload.plaintext === 'string' ? payload.plaintext : '';
+        const scope = typeof payload.scope === 'string' ? payload.scope.trim() : '';
+        if (!plaintext.trim()) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'plaintext must be a non-empty string' }));
+          return;
+        }
+
+        if (!scope) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'scope must be a non-empty string' }));
+          return;
+        }
+        // saleable: commit the DEK-blinded plaintext fold (ZKCP listable)
+        // instead of the E2EE payloadCommit; see /api/zk/sale/* below.
+        const saleable = payload.saleable === true;
+        try {
+          const runtime = await getZkRuntime();
+          const result = await enqueueZkAction(() => runtime.append({ plaintext, scope, saleable }));
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, ...result }));
+
+        } catch (err) {
+          const statusCode = err.code === 'ZK_UNAVAILABLE' ? 503
+            : err.code === 'BAD_REQUEST' ? 400
+            : err.code === 'PROOF_STATE_MISMATCH' ? 409
+              : err.code === 'VK_GATE_REJECTED' ? 409
+                : err.name === 'ProvingAssetError' ? 501
+                  : 500;
+          res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err.message }));
+        }
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/zk/revoke' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'request body must be valid JSON' }));
+          return;
+        }
+        const noteIndex = Number(payload.noteIndex);
+        if (!Number.isInteger(noteIndex) || noteIndex < 0) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'noteIndex must be a non-negative integer' }));
+          return;
+        }
+        try {
+          const runtime = await getZkRuntime();
+          const result = await enqueueZkAction(() => runtime.revoke({ noteIndex }));
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, ...result }));
+
+        } catch (err) {
+          const statusCode = err.code === 'ZK_UNAVAILABLE' ? 503
+            : err.code === 'NOTE_OPENING_MISSING' ? 409
+            : err.code === 'PROOF_STATE_MISMATCH' ? 409
+              : err.code === 'VK_GATE_REJECTED' ? 409
+                : err.name === 'ProvingAssetError' ? 501
+                  : 500;
+          res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err.message }));
+        }
+      });
+      return;
+    }
+    if (url.pathname === '/api/zk/sync-leaves' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'request body must be valid JSON' }));
+          return;
+        }
+        if (!Array.isArray(payload.leaves)) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'leaves must be an array of leaf strings' }));
+          return;
+        }
+        try {
+          const runtime = await getZkRuntime();
+          const result = await enqueueZkAction(() => runtime.syncNoteLeaves(payload.leaves));
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, ...result }));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err.message }));
+        }
+      });
+      return;
+    }
+    // --- GhostMesh Endpoints ---
+    if (url.pathname === '/api/mesh/status' && req.method === 'GET') {
+      try {
+        const node = await getMeshNode();
+        writeJson(res, 200, node.getStatus());
+      } catch (err) {
+        writeJson(res, 500, { ok: false, error: err.message });
+      }
+      return;
+    }
+    if (url.pathname === '/api/mesh/peers' && req.method === 'GET') {
+      try {
+        const node = await getMeshNode();
+        const peers = typeof node.getPeers === 'function' ? node.getPeers() : [];
+        writeJson(res, 200, { ok: true, count: peers.length, peers });
+      } catch (err) {
+        writeJson(res, 500, { ok: false, error: err.message });
+      }
+      return;
+    }
+
+    if (url.pathname === '/api/mesh/announce' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload = {};
+        try { payload = JSON.parse(body || '{}'); } catch {}
+        try {
+          const node = await getMeshNode();
+          const packet = await node.announce(payload.metadata || {});
+          writeJson(res, 200, { ok: true, packetId: packet.subarray(packet.length - 16).toString('hex') });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/mesh/send' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try { payload = JSON.parse(body || '{}'); } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const recipientPub = payload.recipientX25519Pub || payload.recipientEd25519Pub;
+        if (!payload.destination || !recipientPub || !payload.memory) {
+          writeJson(res, 400, { ok: false, error: 'destination, recipientX25519Pub, and memory are required' });
+          return;
+        }
+        try {
+          const node = await getMeshNode();
+          const result = await node.sendEncryptedCapsule(
+            payload.destination,
+            Buffer.from(recipientPub, 'hex'),
+            payload.memory,
+            payload.options || {}
+          );
+          writeJson(res, 200, { ok: true, ...result });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/mesh/gossip-proof' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try { payload = JSON.parse(body || '{}'); } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        try {
+          const node = await getMeshNode();
+          const packet = await node.broadcastZkProof(payload);
+          writeJson(res, 200, { ok: true, packetId: packet.subarray(packet.length - 16).toString('hex') });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/mesh/gossip-sale' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try { payload = JSON.parse(body || '{}'); } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        try {
+          const node = await getMeshNode();
+          const packet = await node.broadcastSealedSaleOffer(payload);
+          writeJson(res, 200, { ok: true, packetId: packet.subarray(packet.length - 16).toString('hex') });
+        } catch (err) {
+          writeJson(res, 500, { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/mesh/inbox' && req.method === 'GET') {
+      writeJson(res, 200, {
+        ok: true,
+        capsules: meshInbox,
+        saleOffers: meshSaleOffers,
+        zkProofs: meshZkProofs,
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/rag/remember' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload = {};
+        try { payload = JSON.parse(body || '{}'); } catch {}
+        if (!payload.text) {
+          writeJson(res, 400, { ok: false, error: 'text is required' });
+          return;
+        }
+        const atomId = payload.id || `atom_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+        const result = await vectorStore.add(atomId, payload.text, {
+          scope: payload.scope || 'enigma.global',
+          importance: payload.importance || 1.0,
+          ...payload.metadata,
+        });
+        persistVectorStore();
+        writeJson(res, 200, { ok: true, id: atomId, ...result });
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/rag/recall' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload = {};
+        try { payload = JSON.parse(body || '{}'); } catch {}
+        if (!payload.query) {
+          writeJson(res, 400, { ok: false, error: 'query is required' });
+          return;
+        }
+        const results = await vectorStore.search(payload.query, {
+          topK: payload.topK || 5,
+          threshold: payload.threshold,
+          scope: payload.scope,
+        });
+        writeJson(res, 200, { ok: true, results, count: results.length });
+      });
+      return;
+    }
+
+    if (url.pathname === '/api/rag/compile-context' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload = {};
+        try { payload = JSON.parse(body || '{}'); } catch {}
+        if (!payload.query) {
+          writeJson(res, 400, { ok: false, error: 'query is required' });
+          return;
+        }
+        const pack = await vectorStore.compileContextPack(payload.query, {
+          maxTokens: payload.maxTokens || 2000,
+          topK: payload.topK || 8,
+          scope: payload.scope,
+        });
+        writeJson(res, 200, { ok: true, ...pack });
+      });
+      return;
+    }
+    // Browser-proving asset manifest. Public ceremony artifacts (no auth), but
+    // fail closed with a clean 404 JSON when any artifact is missing.
+    if (url.pathname === '/api/zk/prover-assets' && req.method === 'GET') {
+      try {
+        const runtime = await getZkRuntime();
+        const files = await proverAssetFiles(runtime);
+        const missing = Object.entries(files).filter(([, file]) => !file || !fs.existsSync(file)).map(([name]) => name);
+        if (missing.length > 0) {
+          writeJson(res, 404, {
+            ok: false,
+            error: `proving artifacts missing: ${missing.map((name) => files[name]).join(', ')}`,
+          });
+          return;
+        }
+        writeJson(res, 200, {
+          ok: true,
+          circuit: 'action_transition',
+          wasmUrl: '/api/zk/prover-assets/action_transition.wasm',
+          zkeyUrl: '/api/zk/prover-assets/action_transition.zkey',
+          snarkjsUrl: '/api/zk/prover-assets/snarkjs.min.js',
+          sizeBytes: {
+            wasm: fs.statSync(files.wasm).size,
+            zkey: fs.statSync(files.zkey).size,
+            snarkjs: fs.statSync(files.snarkjs).size,
+          },
+        });
+      } catch (err) {
+        writeJson(res, 500, { ok: false, error: err.message });
+      }
+      return;
+    }
+
+    // Streams one whitelisted prover artifact (WASM / zkey / snarkjs bundle).
+    if (url.pathname.startsWith('/api/zk/prover-assets/') && req.method === 'GET') {
+      const name = decodeURIComponent(url.pathname.slice('/api/zk/prover-assets/'.length));
+      const route = PROVER_ASSET_ROUTE[name];
+      if (!route) {
+        writeJson(res, 404, { ok: false, error: 'unknown prover asset' });
+        return;
+      }
+      try {
+        const runtime = await getZkRuntime();
+        const file = (await proverAssetFiles(runtime))[route.key];
+        if (!file || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+          writeJson(res, 404, { ok: false, error: `proving artifact not available: ${name}` });
+          return;
+        }
+        res.writeHead(200, {
+          'Content-Type': route.contentType,
+          'Content-Length': fs.statSync(file).size,
+          'Cache-Control': 'no-store',
+        });
+        fs.createReadStream(file).pipe(res);
+      } catch (err) {
+        writeJson(res, 500, { ok: false, error: err.message });
+      }
+      return;
+    }
+
+    // Split phase 1: build and prove entirely inside local custody. The
+    // renderer receives only a single-use opaque handle and public-safe
+    // status metadata; private proving inputs never cross the HTTP boundary.
+    if (url.pathname === '/api/zk/prepare' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const mode = typeof payload.mode === 'string' ? payload.mode : '';
+        if (mode !== 'append' && mode !== 'revoke') {
+          writeJson(res, 400, { ok: false, error: 'mode must be "append" or "revoke"' });
+          return;
+        }
+        let args;
+        if (mode === 'append') {
+          const plaintext = typeof payload.plaintext === 'string' ? payload.plaintext : '';
+          const scope = typeof payload.scope === 'string' ? payload.scope.trim() : '';
+          if (!plaintext.trim()) {
+            writeJson(res, 400, { ok: false, error: 'plaintext must be a non-empty string' });
+            return;
+          }
+          if (!scope) {
+            writeJson(res, 400, { ok: false, error: 'scope must be a non-empty string' });
+            return;
+          }
+
+          args = { plaintext, scope, saleable: payload.saleable === true };
+        } else {
+          const noteIndex = Number(payload.noteIndex);
+          if (!Number.isInteger(noteIndex) || noteIndex < 0) {
+            writeJson(res, 400, { ok: false, error: 'noteIndex must be a non-negative integer' });
+            return;
+          }
+          args = { noteIndex };
+        }
+        try {
+          const runtime = await getZkRuntime();
+          const prepared = await enqueueZkAction(() => (mode === 'append'
+            ? runtime.prepareAppend(args)
+            : runtime.prepareRevoke(args)));
+          const proved = await runtime.provePreparedAction(prepared.witnessInput);
+          const now = Date.now();
+          for (const [id, entry] of pendingPrepares) {
+            if (entry.expiresAt <= now) {
+              clearPendingPrepare(entry);
+              pendingPrepares.delete(id);
+            }
+          }
+          while (pendingPrepares.size >= PREPARE_MAX_SESSIONS) {
+            const oldestId = pendingPrepares.keys().next().value;
+            clearPendingPrepare(pendingPrepares.get(oldestId));
+            pendingPrepares.delete(oldestId);
+          }
+          const prepareId = crypto.randomBytes(16).toString('hex');
+          pendingPrepares.set(prepareId, {
+            mode,
+            pending: prepared.pending,
+            proofBytes: proved.proofBytes,
+            publicInputs: proved.publicInputs,
+            expiresAt: now + PREPARE_TTL_MS,
+          });
+          writeJson(res, 200, {
+            ok: true,
+            prepareId,
+            mode,
+            noteIndex: mode === 'revoke' ? args.noteIndex : null,
+            proofReady: true,
+            publicInputCount: proved.publicInputs.length,
+          });
+
+
+        } catch (err) {
+          const statusCode = err.code === 'ZK_UNAVAILABLE' ? 503
+            : err.code === 'NOTE_OPENING_MISSING' ? 409
+              : err.code === 'BAD_REQUEST' ? 400
+                : err.code === 'VK_GATE_REJECTED' ? 409
+                  : err.name === 'ProvingAssetError' ? 501
+                    : 500;
+          writeJson(res, statusCode, { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    // Split phase 2: append/revoke accept only { mode, prepareId }; the proof
+    // stays attached to the opaque server-side session. Intent mode has no
+    // private note opening and continues to accept public proof material.
+    // The server payer settles, and one in-flight action per mode is allowed.
+    if (url.pathname === '/api/zk/relay' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+          writeJson(res, 400, { ok: false, error: 'request body must be a JSON object' });
+          return;
+        }
+        for (const field of RELAY_FORBIDDEN_FIELDS) {
+          if (field in payload) {
+            writeJson(res, 400, {
+              ok: false,
+              error: `relay request contains forbidden private material ("${field}")`,
+            });
+            return;
+          }
+        }
+        const mode = typeof payload.mode === 'string' ? payload.mode : '';
+        if (mode !== 'append' && mode !== 'revoke' && mode !== 'intent') {
+          writeJson(res, 400, { ok: false, error: 'mode must be "append", "revoke", or "intent"' });
+          return;
+        }
+        if (mode === 'intent') {
+          const shapeError = validateRelayShape(payload.proof, payload.publicInputs, 4);
+          if (shapeError) {
+            writeJson(res, 400, { ok: false, error: shapeError });
+            return;
+          }
+        } else if ('proof' in payload || 'publicInputs' in payload) {
+          writeJson(res, 400, {
+            ok: false,
+            error: 'append/revoke relay accepts only { mode, prepareId }; proof material remains in the opaque local prepare session',
+          });
+          return;
+        }
+        if (relayInFlight.has(mode)) {
+          writeJson(res, 429, { ok: false, error: `relay already in flight for mode "${mode}"` });
+          return;
+        }
+        let prepareEntry = null;
+        if (mode !== 'intent') {
+          const prepareId = typeof payload.prepareId === 'string' ? payload.prepareId : '';
+          prepareEntry = prepareId ? pendingPrepares.get(prepareId) : null;
+          if (!prepareEntry || prepareEntry.expiresAt <= Date.now()) {
+            clearPendingPrepare(prepareEntry);
+            pendingPrepares.delete(prepareId);
+            writeJson(res, 409, { ok: false, error: 'unknown or expired prepare session; re-run /api/zk/prepare and prove again' });
+            return;
+          }
+          if (prepareEntry.mode !== mode) {
+            writeJson(res, 400, { ok: false, error: 'prepareId was issued for a different mode' });
+            return;
+          }
+        }
+        relayInFlight.add(mode);
+        try {
+          const runtime = await getZkRuntime();
+          let proofBytes;
+          let publicInputs;
+          if (mode === 'intent') {
+            proofBytes = {
+              a: Buffer.from(payload.proof.a, 'hex'),
+              b: Buffer.from(payload.proof.b, 'hex'),
+              c: Buffer.from(payload.proof.c, 'hex'),
+            };
+            publicInputs = payload.publicInputs.map((hex) => Buffer.from(hex, 'hex'));
+          } else {
+            proofBytes = prepareEntry.proofBytes;
+            publicInputs = prepareEntry.publicInputs;
+          }
+          let result;
+          if (mode === 'intent') {
+            result = await runtime.relayIntent({ proofBytes, publicInputs });
+          } else {
+            pendingPrepares.delete(payload.prepareId); // prepare sessions are single-use
+            result = await enqueueZkAction(() => runtime.relayAction({ pending: prepareEntry.pending, proofBytes, publicInputs }));
+          }
+          writeJson(res, 200, { ok: true, mode, ...result });
+        
+        } catch (err) {
+          const statusCode = err.code === 'ZK_UNAVAILABLE' ? 503
+            : err.code === 'NOTE_OPENING_MISSING' ? 409
+              : err.code === 'PROOF_STATE_MISMATCH' ? 409
+                : err.code === 'VK_GATE_REJECTED' ? 409
+                  : err.name === 'ProvingAssetError' ? 501
+                    : 500;
+          writeJson(res, statusCode, { ok: false, error: err.message });
+        } finally {
+          if (mode !== 'intent') clearPendingPrepare(prepareEntry);
+          relayInFlight.delete(mode);
+        }
+      });
+      return;
+    }
+
+
+    // Phase 1 (seller): build the sale witness from local custody and prove
+    // locally (~2s). Secrets stay server-side in memory for the request only.
+    if (url.pathname === '/api/zk/sale/prepare-listing' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const forbidden = saleForbiddenField(payload);
+        if (forbidden) {
+          writeJson(res, 400, { ok: false, error: forbidden });
+          return;
+        }
+        const noteIndex = Number(payload.noteIndex ?? payload.noteId);
+        if (!Number.isInteger(noteIndex) || noteIndex < 0) {
+          writeJson(res, 400, { ok: false, error: 'noteIndex (or noteId) must be a non-negative integer' });
+          return;
+        }
+        const price = parseUint64(payload.priceLamports, 'priceLamports');
+        if (price.error) {
+          writeJson(res, 400, { ok: false, error: price.error });
+          return;
+        }
+        const expirySlots = Number(payload.expirySlots);
+        if (!Number.isInteger(expirySlots) || expirySlots < 1 || expirySlots > 2 ** 32) {
+          writeJson(res, 400, { ok: false, error: 'expirySlots must be an integer between 1 and 2^32' });
+          return;
+        }
+        let buyerPub = null;
+        const hasBuyerXY = payload.buyerPubkeyX !== undefined || payload.buyerPubkeyY !== undefined;
+        if (hasBuyerXY) {
+          for (const key of ['buyerPubkeyX', 'buyerPubkeyY']) {
+            if (typeof payload[key] !== 'string' || !/^(0|[1-9][0-9]*)$/.test(payload[key]) || BigInt(payload[key]) >= FR_MODULUS) {
+              writeJson(res, 400, { ok: false, error: `${key} must be a canonical BN254 field element as a decimal string` });
+              return;
+            }
+          }
+          buyerPub = { x: payload.buyerPubkeyX, y: payload.buyerPubkeyY };
+        }
+        const buyerKeyLabel = payload.buyerKeyLabel === undefined ? null : String(payload.buyerKeyLabel);
+        if (!buyerPub && buyerKeyLabel !== null && !/^[a-z0-9_-]{1,64}$/i.test(buyerKeyLabel)) {
+          writeJson(res, 400, { ok: false, error: 'buyerKeyLabel must be 1-64 alphanumeric/-/_ characters' });
+          return;
+        }
+        const mint = payload.mint === undefined ? null : String(payload.mint);
+        try {
+          const runtime = await getZkRuntime();
+          const result = await enqueueZkAction(() => runtime.prepareSaleListing({
+            noteIndex,
+            priceLamports: price.value,
+            buyerPub,
+            buyerKeyLabel,
+            expirySlots,
+            mint,
+          }));
+          writeJson(res, 200, { ok: true, ...result });
+        } catch (err) {
+          writeJson(res, saleErrorStatus(err), { ok: false, error: err.message, ...(err.name === 'ProvingAssetError' ? { code: err.code } : {}) });
+        }
+      });
+      return;
+    }
+
+    // Phase 2 (seller): attest on-chain. Accepts public { proofBytes,
+    // publicInputs, predecessorReceiptRefs? }; the proof binds note state,
+    // commitments, and terms while receipt refs bind lifecycle evidence.
+    if (url.pathname === '/api/zk/sale/submit-listing' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const forbidden = saleForbiddenField(payload);
+        if (forbidden) {
+          writeJson(res, 400, { ok: false, error: forbidden });
+          return;
+        }
+        const shapeError = validateRelayShape(payload.proofBytes, payload.publicInputs, 6);
+        if (shapeError) {
+          writeJson(res, 400, { ok: false, error: shapeError.replace(/^proof\./, 'proofBytes.') });
+          return;
+        }
+        const predecessorRefs = parsePredecessorReceiptRefs(payload.predecessorReceiptRefs);
+        if (predecessorRefs.error) {
+          writeJson(res, 400, { ok: false, error: predecessorRefs.error });
+          return;
+        }
+        try {
+          const runtime = await getZkRuntime();
+          const proofBytes = {
+            a: Buffer.from(payload.proofBytes.a, 'hex'),
+            b: Buffer.from(payload.proofBytes.b, 'hex'),
+            c: Buffer.from(payload.proofBytes.c, 'hex'),
+          };
+          const publicInputs = payload.publicInputs.map((hex) => Buffer.from(hex, 'hex'));
+          const result = await enqueueZkAction(() => runtime.submitSaleListing({
+            proofBytes,
+            publicInputs,
+            predecessorReceiptRefs: predecessorRefs.refs,
+          }));
+          writeJson(res, 200, { ok: true, ...result });
+        } catch (err) {
+          writeJson(res, saleErrorStatus(err), { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    // Buyer pre-payment verification against the on-chain receipt. A failed
+    // check is a verdict, not an error: 200 with ok:false and per-check detail.
+    if (url.pathname === '/api/zk/sale/verify' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const forbidden = saleForbiddenField(payload);
+        if (forbidden) {
+          writeJson(res, 400, { ok: false, error: forbidden });
+          return;
+        }
+        const terms = parseHex32(payload.saleTermsHashHex, 'saleTermsHashHex');
+        const keyCommit = parseHex32(payload.keyCommitHex, 'keyCommitHex');
+        const envelopeCommit = parseHex32(payload.envelopeCommitHex, 'envelopeCommitHex');
+        const chunks = parseCiphertextChunks(payload.ciphertextChunks);
+        for (const parsed of [terms, keyCommit, envelopeCommit, chunks]) {
+          if (parsed.error) {
+            writeJson(res, 400, { ok: false, error: parsed.error });
+            return;
+          }
+        }
+        try {
+          const runtime = await getZkRuntime();
+          const result = await runtime.verifySale({
+            saleTermsHashBytes: terms.bytes,
+            keyCommitBytes: keyCommit.bytes,
+            envelopeCommitBytes: envelopeCommit.bytes,
+            ciphertextChunks: chunks.chunks,
+          });
+          writeJson(res, 200, result);
+        } catch (err) {
+          writeJson(res, saleErrorStatus(err), { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    // Buyer escrow, pinned to the attested receipt; buyer keypair comes from
+    // local custody and never appears on the wire.
+    if (url.pathname === '/api/zk/sale/escrow' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const forbidden = saleForbiddenField(payload);
+        if (forbidden) {
+          writeJson(res, 400, { ok: false, error: forbidden });
+          return;
+        }
+        const terms = parseHex32(payload.saleTermsHashHex, 'saleTermsHashHex');
+        const keyCommit = parseHex32(payload.keyCommitHex, 'keyCommitHex');
+        const envelopeCommit = parseHex32(payload.envelopeCommitHex, 'envelopeCommitHex');
+        const price = parseUint64(payload.priceLamports, 'priceLamports');
+        for (const parsed of [terms, keyCommit, envelopeCommit, price]) {
+          if (parsed.error) {
+            writeJson(res, 400, { ok: false, error: parsed.error });
+            return;
+          }
+        }
+        const expirySlot = Number(payload.expirySlot);
+        if (!Number.isSafeInteger(expirySlot) || expirySlot < 0) {
+          writeJson(res, 400, { ok: false, error: 'expirySlot must be a non-negative safe integer' });
+          return;
+        }
+        const sellerPubkey = typeof payload.sellerPubkey === 'string' ? payload.sellerPubkey.trim() : '';
+        if (!sellerPubkey) {
+          writeJson(res, 400, { ok: false, error: 'sellerPubkey must be a non-empty base58 string' });
+          return;
+        }
+        const mint = typeof payload.mint === 'string' ? payload.mint.trim() : '';
+        if (!mint) {
+          writeJson(res, 400, { ok: false, error: 'mint must be a non-empty base58 string (terms recompute)' });
+          return;
+        }
+        const payloadLen = Number(payload.payloadLen);
+        if (!Number.isSafeInteger(payloadLen) || payloadLen < 1) {
+          writeJson(res, 400, { ok: false, error: 'payloadLen must be a positive safe integer (terms recompute)' });
+          return;
+        }
+        const escrowChunks = parseCiphertextChunks(payload.ciphertextChunks);
+        if (escrowChunks.error) {
+          writeJson(res, 400, { ok: false, error: escrowChunks.error });
+          return;
+        }
+        try {
+          const runtime = await getZkRuntime();
+          const result = await enqueueZkAction(() => runtime.createSaleEscrow({
+            saleTermsHashBytes: terms.bytes,
+            priceLamports: price.value,
+            expirySlot,
+            sellerPubkey,
+            mint,
+            payloadLen,
+            ciphertextChunks: escrowChunks.chunks,
+            buyerKeyLabel: typeof payload.buyerKeyLabel === 'string' ? payload.buyerKeyLabel : undefined,
+            keyCommitBytes: keyCommit.bytes,
+            envelopeCommitBytes: envelopeCommit.bytes,
+          }));
+          writeJson(res, 200, { ok: true, ...result });
+        } catch (err) {
+          writeJson(res, saleErrorStatus(err), { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+
+    // Seller claim: loads the sealed envelope from custody and reveals it
+    // on-chain atomically with payment. The ONLY envelope egress path.
+    if (url.pathname === '/api/zk/sale/claim' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const forbidden = saleForbiddenField(payload);
+        if (forbidden) {
+          writeJson(res, 400, { ok: false, error: forbidden });
+          return;
+        }
+        const terms = parseHex32(payload.saleTermsHashHex, 'saleTermsHashHex');
+        const keyCommit = parseHex32(payload.keyCommitHex, 'keyCommitHex');
+        const envelopeCommit = parseHex32(payload.envelopeCommitHex, 'envelopeCommitHex');
+        for (const parsed of [terms, keyCommit, envelopeCommit]) {
+          if (parsed.error) {
+            writeJson(res, 400, { ok: false, error: parsed.error });
+            return;
+          }
+        }
+        const predecessorRefs = parsePredecessorReceiptRefs(payload.predecessorReceiptRefs);
+        if (predecessorRefs.error) {
+          writeJson(res, 400, { ok: false, error: predecessorRefs.error });
+          return;
+        }
+        const buyerPubkey = typeof payload.buyerPubkey === 'string' ? payload.buyerPubkey.trim() : '';
+        if (!buyerPubkey) {
+          writeJson(res, 400, { ok: false, error: 'buyerPubkey must be a non-empty base58 string' });
+          return;
+        }
+        try {
+          const runtime = await getZkRuntime();
+          const result = await enqueueZkAction(() => runtime.claimSale({
+            saleTermsHashBytes: terms.bytes,
+            buyerPubkey,
+            keyCommitBytes: keyCommit.bytes,
+            envelopeCommitBytes: envelopeCommit.bytes,
+            predecessorReceiptRefs: predecessorRefs.refs,
+          }));
+          writeJson(res, 200, { ok: true, ...result });
+        } catch (err) {
+          writeJson(res, saleErrorStatus(err), { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    // Buyer identity: public keys + SOL balance only — what a fresh install
+    // must fund and hand to sellers. No secrets. Auth required (it is this
+    // device's identity), like the other stateful endpoints.
+    if (url.pathname === '/api/zk/sale/buyer-identity' && req.method === 'GET') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      (async () => {
+        try {
+          const runtime = await getZkRuntime();
+          const identity = await enqueueZkAction(() => runtime.buyerIdentity());
+          writeJson(res, 200, { ok: true, ...identity });
+        } catch (err) {
+          writeJson(res, saleErrorStatus(err), { ok: false, error: err.message });
+        }
+      })();
+      return;
+    }
+
+    // Public receipt view (read-only chain data — no auth, like /api/zk/status).
+    if (url.pathname === '/api/zk/sale/receipt' && req.method === 'GET') {
+      const keyCommit = parseHex32(url.searchParams.get('keyCommit'), 'keyCommit');
+      const envelopeCommit = parseHex32(url.searchParams.get('envelopeCommit'), 'envelopeCommit');
+      for (const parsed of [keyCommit, envelopeCommit]) {
+        if (parsed.error) {
+          writeJson(res, 400, { ok: false, error: parsed.error });
+          return;
+        }
+      }
+      try {
+        const runtime = await getZkRuntime();
+        const { receipt, receiptPda } = await runtime.saleReceipt({
+          keyCommitBytes: keyCommit.bytes,
+          envelopeCommitBytes: envelopeCommit.bytes,
+        });
+        if (!receipt) {
+          writeJson(res, 404, { ok: false, error: 'no sale receipt on-chain for this keyCommit + envelopeCommit pair', receiptPda });
+          return;
+        }
+        writeJson(res, 200, { ok: true, receipt: receiptJson(receipt), receiptPda });
+      } catch (err) {
+        writeJson(res, saleErrorStatus(err), { ok: false, error: err.message });
+      }
+      return;
+    }
+
+    // Buyer post-claim open: decrypts from the on-chain receipt with the
+    // custodied buyer secret. Fails closed (409) while the envelope is zero.
+    if (url.pathname === '/api/zk/sale/open' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        let payload;
+        try {
+          payload = JSON.parse(body || '{}');
+        } catch {
+          writeJson(res, 400, { ok: false, error: 'request body must be valid JSON' });
+          return;
+        }
+        const forbidden = saleForbiddenField(payload);
+        if (forbidden) {
+          writeJson(res, 400, { ok: false, error: forbidden });
+          return;
+        }
+        const keyCommit = parseHex32(payload.keyCommitHex, 'keyCommitHex');
+        const envelopeCommit = parseHex32(payload.envelopeCommitHex, 'envelopeCommitHex');
+        const chunks = parseCiphertextChunks(payload.ciphertextChunks);
+        for (const parsed of [keyCommit, envelopeCommit, chunks]) {
+          if (parsed.error) {
+            writeJson(res, 400, { ok: false, error: parsed.error });
+            return;
+          }
+        }
+        const predecessorRefs = parsePredecessorReceiptRefs(payload.predecessorReceiptRefs);
+        if (predecessorRefs.error) {
+          writeJson(res, 400, { ok: false, error: predecessorRefs.error });
+          return;
+        }
+        let payloadLen = null;
+        if (payload.payloadLen !== undefined) {
+          payloadLen = Number(payload.payloadLen);
+          if (!Number.isInteger(payloadLen) || payloadLen < 0 || payloadLen > 992) {
+            writeJson(res, 400, { ok: false, error: 'payloadLen must be an integer between 0 and 992' });
+            return;
+          }
+        }
+        const buyerKeyLabel = payload.buyerKeyLabel === undefined ? null : String(payload.buyerKeyLabel);
+        try {
+          const runtime = await getZkRuntime();
+          const result = await enqueueZkAction(() => runtime.openSale({
+            keyCommitBytes: keyCommit.bytes,
+            envelopeCommitBytes: envelopeCommit.bytes,
+            ciphertextChunks: chunks.chunks,
+            payloadLen,
+            buyerKeyLabel,
+            predecessorReceiptRefs: predecessorRefs.refs,
+          }));
+          writeJson(res, 200, { ok: true, ...result });
+        } catch (err) {
+          writeJson(res, saleErrorStatus(err), { ok: false, error: err.message });
+        }
+      });
+      return;
+    }
+
+    // Telemetry API
+    if (url.pathname === '/api/telemetry') {
+      try {
+        const metrics = await fetchSolanaStreamMetrics({ cluster: 'mainnet-beta', rpcUrl: SOLANA_MAINNET_RPC });
+        const latencyMs = metrics.latency_ms ?? 0;
+        let epochPct = null;
+        if (typeof metrics.slot_index === 'number' && typeof metrics.slots_in_epoch === 'number' && metrics.slots_in_epoch > 0) {
+          epochPct = Math.min(100, Math.max(0, Number(((metrics.slot_index / metrics.slots_in_epoch) * 100).toFixed(1))));
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          ok: Boolean(metrics.ok),
+          slot: metrics.slot ?? null,
+          epoch: metrics.epoch ?? null,
+          epochPct,
+          latencyMs,
+          latency_ms: latencyMs,
+          slot_index: metrics.slot_index ?? null,
+          slots_in_epoch: metrics.slots_in_epoch ?? null,
+          cluster: 'mainnet-beta',
+          tokenCa: OFFICIAL_TOKEN_CA,
+          connectedWallet: session.connectedWallet || null,
+        }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+      return;
+    }
+
+    // Wallet Status API
+    if (url.pathname === '/api/wallet/status') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        ok: true,
+        connected: Boolean(session.connectedWallet),
+        wallet: session.connectedWallet || null,
+        tokenCa: OFFICIAL_TOKEN_CA,
+      }));
+      return;
+    }
+
+    // Wallet Connect Trigger
+    if (url.pathname === '/api/wallet/connect' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+
+      try {
+        if (!phantomBridge.server) {
+          await phantomBridge.startServer();
+        }
+        const sessionData = phantomBridge.createSession();
+        const companionUrl = await phantomBridge.openInSystemBrowser(sessionData.nonce);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          ok: true,
+          companionUrl,
+          nonce: sessionData.nonce,
+          status: 'opened_in_browser',
+        }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+      return;
+    }
+
+    // Solana RPC Proxy API (eliminates browser CORS/Origin 403 blocks)
+    if (url.pathname === '/api/rpc' && req.method === 'POST') {
+      readBody(req, res, async (body) => {
+        try {
+          const rpcRes = await fetch(SOLANA_MAINNET_RPC, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+          });
+          const rpcText = await rpcRes.text();
+          res.writeHead(rpcRes.status, { 'Content-Type': 'application/json' });
+          res.end(rpcText);
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: err.message }, id: null }));
+        }
+      });
+      return;
+    }
+
+    // Active Anchor Memo payload API
+    if (url.pathname === '/api/active-anchor-memo') {
+      try {
+        if (!fs.existsSync(bundlePath)) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Vault uninitialized. Please initialize your memory vault first (e.g. remember or quickstart).' }));
+          return;
+        }
+
+        let bundleData;
+        try {
+          bundleData = JSON.parse(fs.readFileSync(bundlePath, 'utf8'));
+        } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Unreadable or malformed vault bundle JSON.' }));
+          return;
+        }
+
+        const candidate = bundleData?.bundle && typeof bundleData.bundle === 'object' ? bundleData.bundle : bundleData;
+        const normalized = normalizeSolanaLocalArtifact(candidate, 'mainnet-beta', new Map());
+        const { artifact: anchorBatch, schema } = normalized;
+        const memoRef = createSolanaProofMemoRef(schema, anchorBatch, 'mainnet-beta');
+
+        // Atomically snapshot the exact anchor batch file next to bundle.json
+        const anchorBatchPath = bundlePath.replace(/[^/\\]+$/, 'anchor-batch.json');
+        fs.writeFileSync(anchorBatchPath, JSON.stringify(anchorBatch, null, 2), 'utf8');
+
+        // Fetch latest Mainnet blockhash server-side to guarantee valid transaction blockhash
+        let blockhash = null;
+        let lastValidBlockHeight = null;
+        try {
+          const bhRes = await fetch(SOLANA_MAINNET_RPC, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              jsonrpc: '2.0',
+              id: 'get-latest-blockhash',
+              method: 'getLatestBlockhash',
+              params: [{ commitment: 'confirmed' }],
+            }),
+          });
+          const bhData = await bhRes.json();
+          blockhash = bhData?.result?.value?.blockhash || null;
+          lastValidBlockHeight = bhData?.result?.value?.lastValidBlockHeight || null;
+        } catch {}
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          ok: true,
+          bundlePath,
+          anchorBatchPath,
+          anchorBatch,
+          memoRef,
+          blockhash,
+          lastValidBlockHeight,
+          cluster: 'mainnet-beta',
+          memoProgramId: 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr',
+        }));
+      } catch (err) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+      return;
+    }
+    if (url.pathname === '/api/auto-anchor/status') {
+      try {
+        const isConfigured = autoAnchorEngine.isConfigured();
+        const signerPubkey = autoAnchorEngine.signerStore.getPublicKey();
+        const delegation = autoAnchorEngine.getDelegation();
+        const outboxStats = autoAnchorEngine.outbox.getStats();
+        let balance = null;
+        if (signerPubkey) {
+          try {
+            balance = await autoAnchorEngine.transport.getBalance(signerPubkey);
+          } catch {}
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          ok: true,
+          isConfigured,
+          signerPubkey,
+          delegation,
+          outboxStats,
+          balance,
+          cluster: 'mainnet-beta',
+        }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+      return;
+    }
+
+    // Auto-Anchor Setup Signer API
+    if (url.pathname === '/api/auto-anchor/setup-signer' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      try {
+        const result = autoAnchorEngine.setupSigner();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, signerPubkey: result.publicKeyBase58 }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+      return;
+    }
+
+    // Auto-Anchor Delegation Challenge API
+    if (url.pathname === '/api/auto-anchor/challenge' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        try {
+          const payload = JSON.parse(body || '{}');
+          const ownerPubkey = payload.ownerPubkey || session.connectedWallet?.publicKey;
+          if (!ownerPubkey) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'ownerPubkey required' }));
+            return;
+          }
+          const challengeData = autoAnchorEngine.getDelegationChallenge({ ownerPubkey });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, ...challengeData }));
+        } catch (err) {
+          res.writeHead(500, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err.message }));
+        }
+      });
+      return;
+    }
+
+    // Auto-Anchor Delegation Set API
+    if (url.pathname === '/api/auto-anchor/delegate' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      readBody(req, res, async (body) => {
+        try {
+          const delegation = JSON.parse(body || '{}');
+          autoAnchorEngine.setDelegation(delegation);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: true, isConfigured: true, authorizationHash: delegation.authorization_hash }));
+        } catch (err) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: err.message }));
+        }
+      });
+      return;
+    }
+
+    // Auto-Anchor Process Next Outbox Item API
+    if (url.pathname === '/api/auto-anchor/process' && req.method === 'POST') {
+      if (!validateSecurityHeaders(req, res, { requireAuth: true })) return;
+      try {
+        const result = await autoAnchorEngine.processNextOutboxItem();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, result }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+      return;
+    }
+
+    // Static File Server
+    // Defense in depth: the persisted ZK snapshot contains recipient secret
+    // material and note openings. Reject its filename before static resolution,
+    // even if a caller misconfigures the state path into this directory.
+    if (path.basename(url.pathname).toLowerCase() === 'zk-tree-state.json') {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'Not Found' }));
+      return;
+    }
+    const reqUrl = url.pathname === '/' ? 'index.html' : url.pathname.replace(/^\/+/, '');
+    const safePath = path.normalize(reqUrl).replace(/^(\.\.[\/\\])+/, '').replace(/^[\\\/]+/, '');
+    const filePath = path.join(DESKTOP_DIR, safePath);
+
+    if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not Found');
+      return;
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+
+    if (ext === '.html') {
+      let html = fs.readFileSync(filePath, 'utf8');
+      html = html.replace('__ENIGMA_AUTH_TOKEN__', authToken);
+      // Version is injected at serve time from the package manifest — never
+      // hard-code it in the markup (a stale string ships the wrong identity).
+      html = html.replaceAll('__ENIGMA_VERSION__', ENIGMA_VERSION);
+      res.writeHead(200, { 'Content-Type': contentType });
+      res.end(html);
+      return;
+    }
+
+    res.writeHead(200, { 'Content-Type': contentType });
+    fs.createReadStream(filePath).pipe(res);
+  });
+
+  return {
+    server,
+    session,
+    phantomBridge,
+    autoAnchorEngine,
+    authToken,
+    apiKeys,
+    usage,
+    credits,
+    payments,
+    get port() { return boundPort; },
+    host,
+    listen: () => new Promise((resolve, reject) => {
+      server.listen(boundPort, host, () => {
+        const addr = server.address();
+        boundPort = addr.port;
+        resolve({
+          url: `http://${host}:${boundPort}`,
+          port: boundPort,
+          host,
+          authToken,
+        });
+      });
+      server.on('error', reject);
+    }),
+    close: async () => {
+      if (typeof platformRuntime.close === 'function') {
+        await platformRuntime.close();
+      } else {
+        await platformRuntime.browser?.close?.();
+        await platformRuntime.code?.close?.();
+      }
+      for (const entry of pendingPrepares.values()) clearPendingPrepare(entry);
+      pendingPrepares.clear();
+      await phantomBridge.close();
+      if (federationBridge) {
+        persistOperationalState();
+        await federationBridge.stop();
+      }
+      if (meshNode) await meshNode.stop();
+      if (sdkPromise) {
+        try {
+          const enigma = await sdkPromise;
+          if (typeof enigma.dispose === 'function') await enigma.dispose();
+          else await enigma.rag?.dispose?.();
+        } catch {}
+      }
+      if (ownsVectorStore && ownsEmbeddingProvider) {
+        try {
+          await vectorStore.embedder?.dispose?.();
+        } catch {}
+      }
+      if (ephemeralTempDir && fs.existsSync(ephemeralTempDir)) {
+        try { fs.rmSync(ephemeralTempDir, { recursive: true, force: true }); } catch {}
+      }
+      return new Promise((resolve) => server.close(resolve));
+    },
+  };
+}
+
+export async function startDesktopServer(options = {}) {
+  const desktopServer = createDesktopServer(options);
+  const info = await desktopServer.listen();
+
+  console.log(`\n============================================================`);
+  console.log(`⚡ ENIGMA SOVEREIGN TERMINAL DESKTOP RUNNING`);
+  console.log(`  Origin:             ${info.url}`);
+  console.log(`  Cluster:            Solana Mainnet (mainnet-beta)`);
+  console.log(`  Security Mode:      Hardened Localhost Auth (Strict Host/Origin Check)`);
+  console.log(`============================================================\n`);
+
+  if (options.openBrowser !== false) {
+    const chromePaths = [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    ];
+    const chromeExe = chromePaths.find((p) => fs.existsSync(p));
+
+    if (chromeExe) {
+      spawn(chromeExe, [`--app=${info.url}`, '--window-size=1240,780'], {
+        detached: true,
+        stdio: 'ignore',
+      }).unref();
+    } else {
+      const startCmd = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+      if (process.platform === 'win32') {
+        spawn('cmd.exe', ['/c', 'start', '', info.url], { detached: true, stdio: 'ignore' }).unref();
+      } else {
+        spawn(startCmd, [info.url], { detached: true, stdio: 'ignore' }).unref();
+      }
+    }
+  }
+
+  return desktopServer;
+}