enigma-memory 0.1.18 → 0.1.22

package/packages/mcp-server/src/index.js

@@ -1,7 +1,28 @@
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createHmac, randomBytes } from 'node:crypto';
+import { access, readFile } from 'node:fs/promises';
+import { ENIGMA_VERSION } from '../../core/src/version.mjs';
 import { createInterface } from 'node:readline';
-import { dirname, resolve } from 'node:path';
-import { createVault, remember, recall, deleteMemory, exportBundle } from '../../vault/src/index.js';
+import { resolve } from 'node:path';
+import {
+  createVault,
+  remember,
+  recall,
+  deleteMemory,
+  exportBundle,
+  importBundle,
+  rotateContentKey,
+  sealContentKeyEpoch,
+  resetVaultContentKeys,
+  SimulatedEnclaveProvider,
+  AttestationVerifier,
+  createPoseidonCommitment,
+  verifyPoseidonCommitment,
+} from '../../vault/src/index.js';
+import {
+  readJsonFileWithRevision,
+  withBundleFileLock,
+  writeJsonFileAtomic,
+} from '../../vault/src/persistence.js';
 import { createPassport, compileContextPack } from '../../passport/src/index.js';
 import { verifyBundle } from '../../../apps/verifier/bin/enigma-verify.mjs';
 import { aggregateUsageEvents, createUsageEvent } from '../../metering/src/index.js';
@@ -13,11 +34,126 @@ import {
   createSettlementBatch,
   verifyServiceSettlementReceipt,
 } from '../../settlement/src/index.js';
+import {
+  assertImmuneIngressPublicSafe,
+  createImmuneIngressReport,
+} from '../../importers/src/index.js';
+import {
+  enigma_cluster_memories as routeClusterMemories,
+  enigma_graph_query as routeGraphQuery,
+  enigma_swarm_register_agent as routeSwarmRegisterAgent,
+  enigma_swarm_sync as routeSwarmSync,
+} from '../../connectors/swarm-router.mjs';
+import {
+  DEFAULT_DESKTOP_ORIGIN,
+  PRIVATE_SESSION_RESOURCE_URI,
+  createPrivateSessionHttpUrl,
+  createPrivateSessionProtocolUrl,
+  validateLoopbackDesktopOrigin,
+  validatePrivateHandoffIntent,
+  validatePrivateHandoffModel,
+} from './private-handoff.js';
+import { assertRemoteToolPolicyCoverage, remoteToolPolicy, requiredScopesForMcpPayload } from './remote-policy.js';
+
+
+const defaultEnclave = new SimulatedEnclaveProvider({ simulationLabel: 'enigma_mcp_runtime' });
 
 const DEFAULT_BUNDLE = '.enigma/bundle.json';
 const JSONRPC_VERSION = '2.0';
 const MCP_PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: '0.1.18' });
+const SERVER_INFO = Object.freeze({ name: 'enigma-mcp-server', version: ENIGMA_VERSION });
+const UNLOCKED_VAULT_CACHE_LIMIT = 8;
+const unlockedVaultCache = new Map();
+const cacheAuthenticationKey = randomBytes(32);
+let configuredCheckpointProvider = null;
+let configuredInferenceRuntime = null;
+let configuredX402Client = null;
+const REMOTE_SECURE_VAULT = Symbol('enigma.remote_secure_vault');
+
+function enigmaDesktopOrigin() {
+  return validateLoopbackDesktopOrigin(process.env.ENIGMA_DESKTOP_URL || DEFAULT_DESKTOP_ORIGIN);
+}
+
+function privateSessionUrl(input = {}) {
+  return process.env.ENIGMA_DESKTOP_URL
+    ? createPrivateSessionHttpUrl(input, enigmaDesktopOrigin())
+    : createPrivateSessionProtocolUrl(input);
+}
+
+function rejectSensitiveHandoffIntent(intent) {
+  try {
+    validatePrivateHandoffIntent(intent);
+  } catch (error) {
+    throw invalidParams(error.message);
+  }
+}
+
+export function configureVaultCheckpointProvider(provider = null) {
+  if (provider !== null && (typeof provider?.load !== 'function' || typeof provider?.advance !== 'function')) {
+    throw new TypeError('checkpoint provider requires load and advance functions');
+  }
+  configuredCheckpointProvider = provider;
+}
+
+export function configureMcpInferenceRuntime(runtime = null) {
+  const hasChat = typeof runtime?.chat?.complete === 'function';
+  const hasImages = typeof runtime?.images?.generate === 'function';
+  if (runtime !== null && !hasChat && !hasImages) {
+    throw new TypeError('MCP inference runtime requires chat.complete() or images.generate()');
+  }
+  configuredInferenceRuntime = runtime;
+}
+
+export function configureMcpX402Client(client = null) {
+  if (client !== null && typeof client !== 'function') throw new TypeError('MCP x402 client must be a function');
+  configuredX402Client = client;
+}
+
+function credentialCacheTag(credentials) {
+  return createHmac('sha256', cacheAuthenticationKey)
+    .update(credentials.passphrase ?? (credentials.insecureDevMode ? 'insecure-dev' : 'missing'))
+    .digest('hex');
+}
+
+function zeroizeCachedVault(entry) {
+  const vault = entry?.vault;
+  if (!vault) return;
+  for (const epoch of vault.keyEpochs?.values?.() ?? []) epoch.key?.fill?.(0);
+  vault.addressKey?.fill?.(0);
+  for (const record of vault.memories?.values?.() ?? []) {
+    if (Object.prototype.hasOwnProperty.call(record, 'plaintext')) delete record.plaintext;
+  }
+}
+
+function invalidateCachedVault(path) {
+  const key = resolve(String(path));
+  const prior = unlockedVaultCache.get(key);
+  unlockedVaultCache.delete(key);
+  zeroizeCachedVault(prior);
+}
+
+function cacheUnlockedVault(path, entry) {
+  const key = resolve(String(path));
+  const prior = unlockedVaultCache.get(key);
+  if (prior && prior.vault !== entry.vault) zeroizeCachedVault(prior);
+  unlockedVaultCache.delete(key);
+  unlockedVaultCache.set(key, entry);
+  while (unlockedVaultCache.size > UNLOCKED_VAULT_CACHE_LIMIT) {
+    const oldestKey = unlockedVaultCache.keys().next().value;
+    const oldest = unlockedVaultCache.get(oldestKey);
+    unlockedVaultCache.delete(oldestKey);
+    zeroizeCachedVault(oldest);
+  }
+}
+export function clearUnlockedVaultCache() {
+  for (const entry of unlockedVaultCache.values()) zeroizeCachedVault(entry);
+  unlockedVaultCache.clear();
+}
+
+process.once('exit', () => {
+  clearUnlockedVaultCache();
+  cacheAuthenticationKey.fill(0);
+});
 const JSON_RPC_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 const JSON_RPC_ERROR = Object.freeze({
   INVALID_REQUEST: -32600,
@@ -121,28 +257,131 @@ function optionalObjectArray(object, key, context) {
   }
 }
 
+function optionalIntegerRange(object, key, context, minimum, maximum) {
+  if (object[key] === undefined) return;
+  if (!Number.isInteger(object[key]) || object[key] < minimum || object[key] > maximum) {
+    throw invalidParams(`${context} ${key} must be an integer from ${minimum} through ${maximum}.`);
+  }
+}
+
+function optionalPermissionMask(object, key, context) {
+  const value = object[key];
+  if (value === undefined) return;
+  const validNumber = Number.isInteger(value) && value >= 0 && value <= 63;
+  const validString = typeof value === 'string';
+  const validArray = Array.isArray(value) && value.every((item) => typeof item === 'string');
+  if (!validNumber && !validString && !validArray) {
+    throw invalidParams(`${context} ${key} must be a permission bitmask, string, or array of strings.`);
+  }
+}
+
+function maximumStringLength(object, key, context, maximum) {
+  if (typeof object[key] === 'string' && object[key].length > maximum) {
+    throw invalidParams(`${context} ${key} exceeds ${maximum} characters.`);
+  }
+}
+
+function validateCompletionMessages(messages, context) {
+  if (!Array.isArray(messages) || messages.length < 1 || messages.length > 128) {
+    throw invalidParams(`${context} messages must contain one through 128 messages.`);
+  }
+  for (const [index, message] of messages.entries()) {
+    if (!isPlainObject(message)) throw invalidParams(`${context} messages[${index}] must be an object.`);
+    rejectAdditionalProperties(message, new Set(['role', 'content']), `${context} messages[${index}]`);
+    requireString(message, 'role', `${context} messages[${index}]`);
+    requireString(message, 'content', `${context} messages[${index}]`);
+    if (!['system', 'user', 'assistant', 'tool'].includes(message.role)) {
+      throw invalidParams(`${context} messages[${index}].role is invalid.`);
+    }
+    if (message.content.length > 100_000) throw invalidParams(`${context} messages[${index}].content exceeds 100000 characters.`);
+  }
+}
+
 function validateToolArguments(name, args) {
   if (!isPlainObject(args)) throw invalidParams('tools/call arguments must be an object.');
   switch (name) {
+    case 'enigma_private_handoff_health':
+    case 'enigma_routing_contract':
+      rejectAdditionalProperties(args, new Set(), name);
+      return args;
+    case 'enigma_complete':
+      rejectAdditionalProperties(args, new Set(['messages', 'model', 'privacy_mode', 'temperature', 'max_tokens', 'reasoning_effort', 'web_search', 'require_private_route']), name);
+      validateCompletionMessages(args.messages, name);
+      optionalString(args, 'model', name);
+      maximumStringLength(args, 'model', name, 160);
+      optionalString(args, 'privacy_mode', name);
+      if (args.privacy_mode !== undefined && !['off', 'smart', 'full'].includes(args.privacy_mode)) throw invalidParams(`${name} privacy_mode must be off, smart, or full.`);
+      optionalNonNegativeNumber(args, 'temperature', name);
+      if (args.temperature !== undefined && args.temperature > 2) throw invalidParams(`${name} temperature must not exceed 2.`);
+      optionalIntegerRange(args, 'max_tokens', name, 1, 131072);
+      optionalString(args, 'reasoning_effort', name);
+      if (args.reasoning_effort !== undefined && !['none', 'low', 'medium', 'high'].includes(args.reasoning_effort)) throw invalidParams(`${name} reasoning_effort is invalid.`);
+      optionalBoolean(args, 'web_search', name);
+      optionalBoolean(args, 'require_private_route', name);
+      return args;
+    case 'enigma_generate_image':
+      rejectAdditionalProperties(args, new Set(['prompt', 'model', 'negative_prompt', 'width', 'height', 'steps', 'cfg_scale', 'variants', 'format', 'seed']), name);
+      requireString(args, 'prompt', name);
+      requireString(args, 'model', name);
+      optionalString(args, 'negative_prompt', name);
+      maximumStringLength(args, 'prompt', name, 16000);
+      maximumStringLength(args, 'model', name, 160);
+      maximumStringLength(args, 'negative_prompt', name, 8000);
+      optionalIntegerRange(args, 'width', name, 256, 2048);
+      optionalIntegerRange(args, 'height', name, 256, 2048);
+      optionalIntegerRange(args, 'steps', name, 1, 100);
+      optionalNonNegativeNumber(args, 'cfg_scale', name);
+      if (args.cfg_scale !== undefined && (args.cfg_scale < 1 || args.cfg_scale > 30)) throw invalidParams(`${name} cfg_scale must be from 1 through 30.`);
+      optionalIntegerRange(args, 'variants', name, 1, 4);
+      optionalString(args, 'format', name);
+      if (args.format !== undefined && !['png', 'jpeg', 'webp'].includes(args.format)) throw invalidParams(`${name} format must be png, jpeg, or webp.`);
+      optionalIntegerRange(args, 'seed', name, 0, 2147483647);
+      return args;
+    case 'enigma_x402_execute':
+      rejectAdditionalProperties(args, new Set(['url', 'method', 'headers', 'body', 'max_response_bytes']), name);
+      requireString(args, 'url', name);
+      maximumStringLength(args, 'url', name, 4096);
+      optionalString(args, 'method', name);
+      if (args.method !== undefined && !['GET', 'POST'].includes(args.method)) throw invalidParams(`${name} method must be GET or POST.`);
+      optionalPlainObject(args, 'headers', name);
+      for (const [header, value] of Object.entries(args.headers || {})) {
+        if (!['accept', 'content-type', 'idempotency-key'].includes(header.toLowerCase()) || typeof value !== 'string' || value.length > 4096) {
+          throw invalidParams(`${name} contains a forbidden or invalid request header.`);
+        }
+      }
+      if (args.body !== undefined && typeof args.body !== 'string' && !isPlainObject(args.body)) throw invalidParams(`${name} body must be a string or object.`);
+      optionalIntegerRange(args, 'max_response_bytes', name, 1024, 1048576);
+      return args;
+    case 'enigma_start_private_session':
+      rejectAdditionalProperties(args, new Set(['intent', 'model']), name);
+      optionalString(args, 'intent', name);
+      optionalString(args, 'model', name);
+      rejectSensitiveHandoffIntent(args.intent);
+      try { validatePrivateHandoffModel(args.model); } catch (error) { throw invalidParams(error.message); }
+      return args;
     case 'enigma_init':
-      rejectAdditionalProperties(args, new Set(['bundlePath', 'tenant_id', 'subject_id', 'actor_id', 'policy_id']), name);
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'tenant_id', 'subject_id', 'actor_id', 'policy_id', 'insecureDevMode']), name);
       optionalString(args, 'bundlePath', name);
+      optionalBoolean(args, 'insecureDevMode', name);
       optionalString(args, 'tenant_id', name);
       optionalString(args, 'subject_id', name);
       optionalString(args, 'actor_id', name);
       optionalString(args, 'policy_id', name);
       return args;
     case 'enigma_remember':
-      rejectAdditionalProperties(args, new Set(['bundlePath', 'text', 'purpose', 'tags', 'metadata']), name);
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'text', 'purpose', 'tags', 'metadata', 'insecureDevMode']), name);
       optionalString(args, 'bundlePath', name);
+      optionalBoolean(args, 'insecureDevMode', name);
       requireString(args, 'text', name);
       optionalString(args, 'purpose', name);
       optionalStringArray(args, 'tags', name);
       optionalPlainObject(args, 'metadata', name);
       return args;
     case 'enigma_search':
-      rejectAdditionalProperties(args, new Set(['bundlePath', 'query', 'memory_addr', 'purpose', 'limit']), name);
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'query', 'memory_addr', 'purpose', 'limit', 'insecureDevMode', 'allowOldEpochReads']), name);
       optionalString(args, 'bundlePath', name);
+      optionalBoolean(args, 'insecureDevMode', name);
+      optionalBoolean(args, 'allowOldEpochReads', name);
       optionalString(args, 'query', name);
       optionalString(args, 'memory_addr', name);
       optionalString(args, 'purpose', name);
@@ -159,8 +398,12 @@ function validateToolArguments(name, args) {
         'max_estimated_tokens',
         'price_per_million_tokens',
         'currency',
+        'insecureDevMode',
+        'allowOldEpochReads',
       ]), name);
       optionalString(args, 'bundlePath', name);
+      optionalBoolean(args, 'insecureDevMode', name);
+      optionalBoolean(args, 'allowOldEpochReads', name);
       optionalString(args, 'query', name);
       optionalString(args, 'purpose', name);
       optionalLimit(args, 'limit', name);
@@ -171,16 +414,85 @@ function validateToolArguments(name, args) {
       optionalString(args, 'currency', name);
       return args;
     case 'enigma_delete':
-      rejectAdditionalProperties(args, new Set(['bundlePath', 'memory_addr', 'reason']), name);
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'memory_addr', 'reason', 'insecureDevMode']), name);
       optionalString(args, 'bundlePath', name);
+      optionalBoolean(args, 'insecureDevMode', name);
       requireString(args, 'memory_addr', name);
       optionalString(args, 'reason', name);
       return args;
+    case 'enigma_vault_rotate':
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'key_id', 'insecureDevMode']), name);
+      optionalString(args, 'bundlePath', name);
+      optionalString(args, 'key_id', name);
+      optionalBoolean(args, 'insecureDevMode', name);
+      return args;
+    case 'enigma_vault_seal':
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'epoch', 'insecureDevMode']), name);
+      optionalString(args, 'bundlePath', name);
+      optionalIntegerRange(args, 'epoch', name, 1, Number.MAX_SAFE_INTEGER);
+      optionalBoolean(args, 'insecureDevMode', name);
+      return args;
+    case 'enigma_vault_reset':
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'key_id', 'insecureDevMode']), name);
+      optionalString(args, 'bundlePath', name);
+      optionalString(args, 'key_id', name);
+      optionalBoolean(args, 'insecureDevMode', name);
+      return args;
     case 'enigma_verify_receipts':
       rejectAdditionalProperties(args, new Set(['bundlePath', 'bundle']), name);
       optionalString(args, 'bundlePath', name);
       optionalPlainObject(args, 'bundle', name);
       return args;
+    case 'enigma_swarm_register_agent':
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'agent_id', 'swarm_id', 'namespace', 'permission_mask']), name);
+      optionalString(args, 'bundlePath', name);
+      requireString(args, 'agent_id', name);
+      optionalString(args, 'swarm_id', name);
+      optionalString(args, 'namespace', name);
+      optionalPermissionMask(args, 'permission_mask', name);
+      return args;
+    case 'enigma_graph_query':
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'agent_id', 'swarm_id', 'namespace', 'start', 'entity_id', 'query', 'max_depth', 'limit', 'direction']), name);
+      optionalString(args, 'bundlePath', name);
+      requireString(args, 'agent_id', name);
+      optionalString(args, 'swarm_id', name);
+      optionalString(args, 'namespace', name);
+      optionalString(args, 'start', name);
+      optionalString(args, 'entity_id', name);
+      optionalString(args, 'query', name);
+      optionalIntegerRange(args, 'max_depth', name, 0, 12);
+      optionalIntegerRange(args, 'limit', name, 1, 500);
+      optionalString(args, 'direction', name);
+      return args;
+    case 'enigma_cluster_memories':
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'agent_id', 'swarm_id', 'namespace', 'threshold', 'max_clusters']), name);
+      optionalString(args, 'bundlePath', name);
+      requireString(args, 'agent_id', name);
+      optionalString(args, 'swarm_id', name);
+      optionalString(args, 'namespace', name);
+      optionalNonNegativeNumber(args, 'threshold', name);
+      if (args.threshold !== undefined && args.threshold > 1) throw invalidParams(`${name} threshold must not exceed 1.`);
+      optionalIntegerRange(args, 'max_clusters', name, 1, 100);
+      return args;
+    case 'enigma_swarm_sync':
+      rejectAdditionalProperties(args, new Set(['bundlePath', 'agent_id', 'swarm_id', 'namespace', 'snapshot', 'apply', 'include_content', 'allow_content']), name);
+      optionalString(args, 'bundlePath', name);
+      requireString(args, 'agent_id', name);
+      optionalString(args, 'swarm_id', name);
+      optionalString(args, 'namespace', name);
+      optionalPlainObject(args, 'snapshot', name);
+      optionalBoolean(args, 'apply', name);
+      optionalBoolean(args, 'include_content', name);
+      optionalBoolean(args, 'allow_content', name);
+      return args;
+    case 'enigma_immune_ingress':
+      rejectAdditionalProperties(args, new Set(['candidate', 'candidates', 'generated_at', 'now']), name);
+      optionalPlainObject(args, 'candidate', name);
+      optionalObjectArray(args, 'candidates', name);
+      optionalString(args, 'generated_at', name);
+      optionalString(args, 'now', name);
+      if (args.candidate === undefined && args.candidates === undefined) throw invalidParams(`${name} requires candidate or candidates.`);
+      return args;
     case 'enigma_meter_usage':
       rejectAdditionalProperties(args, new Set([
         'events',
@@ -291,6 +603,28 @@ function validateToolArguments(name, args) {
       requireString(args, 'batch_ref', name);
       optionalString(args, 'generated_at', name);
       return args;
+    case 'enigma_vault_create_record':
+      rejectAdditionalProperties(args, new Set(['plaintext', 'metadata']), name);
+      requireString(args, 'plaintext', name);
+      optionalPlainObject(args, 'metadata', name);
+      return args;
+    case 'enigma_vault_zeroize_record':
+      rejectAdditionalProperties(args, new Set(['recordId']), name);
+      requireString(args, 'recordId', name);
+      return args;
+    case 'enigma_verify_erasure_attestation':
+      rejectAdditionalProperties(args, new Set(['attestation', 'allowSimulated', 'expectedPcr']), name);
+      optionalPlainObject(args, 'attestation', name);
+      optionalBoolean(args, 'allowSimulated', name);
+      optionalString(args, 'expectedPcr', name);
+      if (!args.attestation) throw invalidParams(`${name} requires attestation object.`);
+      return args;
+    case 'enigma_nullifier_record_tombstone':
+      rejectAdditionalProperties(args, new Set(['commitment', 'nullifierHash', 'ownerPubkey']), name);
+      requireString(args, 'commitment', name);
+      requireString(args, 'nullifierHash', name);
+      requireString(args, 'ownerPubkey', name);
+      return args;
     default:
       throw invalidParams('Unknown tool.');
   }
@@ -305,6 +639,117 @@ function validatePromptArguments(args) {
   return args;
 }
 
+function remoteToolDescriptors() {
+  assertRemoteToolPolicyCoverage(toolDescriptors);
+  return toolDescriptors.map((descriptor) => {
+    const policy = remoteToolPolicy(descriptor.name);
+    const forbidden = new Set(policy.clientForbiddenFields);
+    const schema = descriptor.inputSchema;
+    if (!schema?.properties || forbidden.size === 0) return descriptor;
+    const properties = Object.fromEntries(Object.entries(schema.properties).filter(([name]) => !forbidden.has(name)));
+    const required = Array.isArray(schema.required) ? schema.required.filter((name) => !forbidden.has(name)) : undefined;
+    return {
+      ...descriptor,
+      inputSchema: {
+        ...schema,
+        properties,
+        ...(required === undefined ? {} : { required }),
+      },
+    };
+  });
+}
+
+function assertNestedTenantBinding(value, tenantId, { required = false } = {}) {
+  let found = 0;
+  function visit(candidate) {
+    if (Array.isArray(candidate)) {
+      candidate.forEach(visit);
+      return;
+    }
+    if (!isPlainObject(candidate)) return;
+    for (const [key, child] of Object.entries(candidate)) {
+      if (key === 'tenant_id' || key === 'tenantId') {
+        found += 1;
+        if (child !== tenantId) throw invalidParams('Remote MCP settlement or metering input belongs to a different tenant.');
+      }
+      visit(child);
+    }
+  }
+  visit(value);
+  if (required && found === 0) throw invalidParams('Remote MCP input does not contain the server-bound tenant.');
+}
+
+async function bindRemoteToolArguments(name, args, context) {
+  if (context.transport !== 'streamable-http') return args;
+  if (!isPlainObject(args)) throw invalidParams('tools/call arguments must be an object.');
+  const policy = remoteToolPolicy(name);
+  if (!policy) throw invalidParams('Remote MCP policy is missing for this tool.');
+  const forbidden = Object.keys(args).find((key) => policy.clientForbiddenFields.includes(key));
+  if (forbidden) throw invalidParams(`Remote MCP does not accept client-controlled ${forbidden}.`);
+  const requiresBinding = policy.vaultBinding !== 'none' || policy.tenantBinding !== 'none';
+  let binding = null;
+  if (requiresBinding) {
+    if (typeof context.resolveVaultContext !== 'function') throw new Error('remote tenant and vault resolver is not configured');
+    binding = await context.resolveVaultContext(context.principal);
+    if (!isPlainObject(binding) || typeof binding.tenant_id !== 'string' || !binding.tenant_id) {
+      throw new Error('remote tenant and vault resolver returned an invalid binding');
+    }
+  }
+  let bound = { ...args };
+  if (policy.vaultBinding !== 'none') {
+    if (typeof binding.bundlePath !== 'string' || !binding.bundlePath) throw new Error('remote vault resolver returned no bundle path');
+    bound.bundlePath = binding.bundlePath;
+    if (name === 'enigma_init') {
+      bound = {
+        ...bound,
+        tenant_id: binding.tenant_id,
+        subject_id: String(binding.subject_id || ''),
+        actor_id: String(binding.actor_id || ''),
+        policy_id: String(binding.policy_id || ''),
+      };
+    }
+    if (name === 'enigma_search' || name === 'enigma_context_pack') bound.allowOldEpochReads = false;
+    Object.defineProperty(bound, REMOTE_SECURE_VAULT, { value: true, enumerable: true });
+  }
+  if (policy.tenantBinding === 'inject') {
+    if (name === 'enigma_meter_usage' && Array.isArray(bound.events)) {
+      assertNestedTenantBinding(bound.events, binding.tenant_id, { required: true });
+    }
+    bound.tenant_id = binding.tenant_id;
+  } else if (policy.tenantBinding === 'validate_nested') {
+    assertNestedTenantBinding(bound, binding.tenant_id, { required: true });
+  }
+  return validateToolArguments(name, bound);
+}
+
+async function bindRemoteResourceInput(params, normalizedUri, context) {
+  if (context.transport !== 'streamable-http' || normalizedUri !== PASSPORT_SUMMARY_RESOURCE_URI) return inputWithBundlePath(params);
+  const forbiddenFields = new Set(['bundlePath', 'bundle_path', 'insecureDevMode', 'insecure_dev_mode']);
+  const parsed = new URL(String(params.uri));
+  const forbiddenQuery = [...parsed.searchParams.keys()].find((key) => forbiddenFields.has(key));
+  const forbiddenProperty = Object.keys(params).find((key) => forbiddenFields.has(key));
+  if (forbiddenQuery || forbiddenProperty) throw invalidParams(`Remote MCP does not accept client-controlled ${forbiddenQuery || forbiddenProperty}.`);
+  if (typeof context.resolveVaultContext !== 'function') throw new Error('remote vault resolver is not configured');
+  const binding = await context.resolveVaultContext(context.principal);
+  if (!isPlainObject(binding) || typeof binding.bundlePath !== 'string' || !binding.bundlePath) {
+    throw new Error('remote vault resolver returned an invalid binding');
+  }
+  const bound = { uri: params.uri, bundlePath: binding.bundlePath };
+  Object.defineProperty(bound, REMOTE_SECURE_VAULT, { value: true, enumerable: true });
+  return bound;
+}
+
+function sanitizeRemoteCustodyOutput(value, context) {
+  if (context.transport !== 'streamable-http' || !value || typeof value !== 'object' || Buffer.isBuffer(value) || value instanceof Uint8Array) return value;
+  if (Array.isArray(value)) return value.map((item) => sanitizeRemoteCustodyOutput(item, context));
+  const sanitized = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === 'bundlePath' || key === 'bundle_path') continue;
+    sanitized[key] = sanitizeRemoteCustodyOutput(item, context);
+  }
+  return sanitized;
+}
+
 function sanitizeOperationalError(error) {
   return {
     ok: false,
@@ -313,8 +758,148 @@ function sanitizeOperationalError(error) {
   };
 }
 
+function mcpImmuneIngressCandidates(input) {
+  if (!isPlainObject(input)) return input;
+  if (Object.prototype.hasOwnProperty.call(input, 'candidates')) return input.candidates;
+  if (Object.prototype.hasOwnProperty.call(input, 'candidate')) return input.candidate;
+  if (Object.prototype.hasOwnProperty.call(input, 'memory_candidates')) return input.memory_candidates;
+  if (Object.prototype.hasOwnProperty.call(input, 'memoryCandidates')) return input.memoryCandidates;
+  return input;
+}
+
+function mcpImmuneIngressOptions(input, options = {}) {
+  return {
+    ...options,
+    now: options.now ?? input?.now ?? input?.generated_at ?? input?.generatedAt,
+    source_type: options.source_type ?? options.sourceType ?? 'mcp_candidate_ingress',
+  };
+}
+
+export function createMcpImmuneIngressReport(input = {}, options = {}) {
+  return createImmuneIngressReport(mcpImmuneIngressCandidates(input), mcpImmuneIngressOptions(input, options));
+}
+
+export function assertMcpImmuneIngressPublicSafe(input = {}, options = {}) {
+  return assertImmuneIngressPublicSafe(mcpImmuneIngressCandidates(input), mcpImmuneIngressOptions(input, options));
+}
+
 
 export const toolDescriptors = [
+  {
+    name: 'enigma_private_handoff_health',
+    description: 'Check whether the local Enigma private workspace is reachable. This diagnostic never accepts or returns a user prompt.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_routing_contract',
+    description: 'Explain when an MCP host must use an Enigma private-session handoff instead of relaying prompt text through host-visible tool arguments.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_start_private_session',
+    description: 'Open the Enigma private workspace for sensitive prompts. Pass only a non-sensitive intent label; the actual prompt must be typed inside Enigma and never placed in this tool call.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          maxLength: 160,
+          description: 'Optional non-sensitive handoff label such as "private legal question". Never include the actual private prompt.',
+        },
+        model: {
+          type: 'string',
+          maxLength: 160,
+          description: 'Optional configured Enigma model route to preselect.',
+        },
+      },
+      additionalProperties: false,
+    },
+    _meta: {
+      'openai/outputTemplate': PRIVATE_SESSION_RESOURCE_URI,
+      'ui/resourceUri': PRIVATE_SESSION_RESOURCE_URI,
+    },
+  },
+  {
+    name: 'enigma_complete',
+    description: 'Run a direct Enigma completion with Smart Privacy and explicit route disclosure. MCP tool arguments are visible to the MCP host; use enigma_start_private_session when the prompt must remain outside host chat.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        messages: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 128,
+          items: {
+            type: 'object',
+            properties: {
+              role: { type: 'string', enum: ['system', 'user', 'assistant', 'tool'] },
+              content: { type: 'string', maxLength: 100000 },
+            },
+            required: ['role', 'content'],
+            additionalProperties: false,
+          },
+        },
+        model: { type: 'string', default: 'enigma-auto' },
+        privacy_mode: { type: 'string', enum: ['off', 'smart', 'full'], default: 'smart' },
+        temperature: { type: 'number', minimum: 0, maximum: 2 },
+        max_tokens: { type: 'integer', minimum: 1, maximum: 131072 },
+        reasoning_effort: { type: 'string', enum: ['none', 'low', 'medium', 'high'] },
+        web_search: { type: 'boolean', default: false },
+        require_private_route: { type: 'boolean', default: false },
+      },
+      required: ['messages'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_generate_image',
+    description: 'Generate image assets through a configured Enigma image route. The prompt is sent only to that configured route and is not retained in the MCP receipt.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', maxLength: 16000 },
+        model: { type: 'string', maxLength: 160 },
+        negative_prompt: { type: 'string', maxLength: 8000 },
+        width: { type: 'integer', minimum: 256, maximum: 2048, default: 1024 },
+        height: { type: 'integer', minimum: 256, maximum: 2048, default: 1024 },
+        steps: { type: 'integer', minimum: 1, maximum: 100, default: 30 },
+        cfg_scale: { type: 'number', minimum: 1, maximum: 30, default: 7.5 },
+        variants: { type: 'integer', minimum: 1, maximum: 4, default: 1 },
+        format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'webp' },
+        seed: { type: 'integer', minimum: 0, maximum: 2147483647 },
+      },
+      required: ['prompt', 'model'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_x402_execute',
+    description: 'Execute an x402 v2 paid HTTP request using the configured real wallet signer, strict recipient/network/asset allowlists, and an atomic-unit budget. This moves funds; inspect the server offer before calling.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', maxLength: 4096 },
+        method: { type: 'string', enum: ['GET', 'POST'], default: 'GET' },
+        headers: {
+          type: 'object',
+          description: 'Only Accept, Content-Type, and Idempotency-Key are allowed.',
+          additionalProperties: { type: 'string', maxLength: 4096 },
+        },
+        body: { anyOf: [{ type: 'string' }, { type: 'object' }] },
+        max_response_bytes: { type: 'integer', minimum: 1024, maximum: 1048576, default: 262144 },
+      },
+      required: ['url'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'enigma_init',
     description: 'Create a local Enigma vault bundle when one does not already exist.',
@@ -326,6 +911,7 @@ export const toolDescriptors = [
         subject_id: { type: 'string' },
         actor_id: { type: 'string' },
         policy_id: { type: 'string' },
+        insecureDevMode: { type: 'boolean', description: 'Explicitly allow a plaintext disposable development bundle when no server passphrase is configured.' },
       },
       additionalProperties: false,
     },
@@ -341,6 +927,7 @@ export const toolDescriptors = [
         purpose: { type: 'string' },
         tags: { type: 'array', items: { type: 'string' } },
         metadata: { type: 'object' },
+        insecureDevMode: { type: 'boolean' },
       },
       required: ['text'],
       additionalProperties: false,
@@ -357,6 +944,8 @@ export const toolDescriptors = [
         memory_addr: { type: 'string' },
         purpose: { type: 'string' },
         limit: { type: 'integer', minimum: 1, maximum: 50 },
+        insecureDevMode: { type: 'boolean' },
+        allowOldEpochReads: { type: 'boolean' },
       },
       additionalProperties: false,
     },
@@ -376,6 +965,8 @@ export const toolDescriptors = [
         max_estimated_tokens: { type: 'number', minimum: 0 },
         price_per_million_tokens: { type: 'number', minimum: 0 },
         currency: { type: 'string' },
+        insecureDevMode: { type: 'boolean' },
+        allowOldEpochReads: { type: 'boolean' },
       },
       additionalProperties: false,
     },
@@ -389,11 +980,51 @@ export const toolDescriptors = [
         bundlePath: { type: 'string' },
         memory_addr: { type: 'string' },
         reason: { type: 'string' },
+        insecureDevMode: { type: 'boolean' },
       },
       required: ['memory_addr'],
       additionalProperties: false,
     },
   },
+  {
+    name: 'enigma_vault_rotate',
+    description: 'Rotate to a new content-key epoch while honestly retaining prior keys for authorized historical reads.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundlePath: { type: 'string' },
+        key_id: { type: 'string' },
+        insecureDevMode: { type: 'boolean' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_vault_seal',
+    description: 'Seal a content-key epoch against future writes while retaining its key for policy-authorized reads.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundlePath: { type: 'string' },
+        epoch: { type: 'integer', minimum: 1 },
+        insecureDevMode: { type: 'boolean' },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_vault_reset',
+    description: 'Perform a software content-key reset, remove local records, and emit signed evidence without claiming physical-media, backup, or external-copy erasure.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundlePath: { type: 'string' },
+        key_id: { type: 'string' },
+        insecureDevMode: { type: 'boolean' },
+      },
+      additionalProperties: false,
+    },
+  },
   {
     name: 'enigma_verify_receipts',
     description: 'Verify receipts/checkpoints in a local or exported Enigma bundle and return a machine-readable verdict.',
@@ -406,6 +1037,99 @@ export const toolDescriptors = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'enigma_swarm_register_agent',
+    description: 'Register an agent in a local swarm domain with a namespace fence and explicit permission mask.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundlePath: { type: 'string' },
+        agent_id: { type: 'string' },
+        swarm_id: { type: 'string' },
+        namespace: { type: 'string' },
+        permission_mask: {
+          oneOf: [
+            { type: 'integer', minimum: 0, maximum: 63 },
+            { type: 'string' },
+            { type: 'array', items: { type: 'string' } },
+          ],
+        },
+      },
+      required: ['agent_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_graph_query',
+    description: 'Traverse the namespace-fenced local memory entity graph, including cross-atom associative links.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundlePath: { type: 'string' },
+        agent_id: { type: 'string' },
+        swarm_id: { type: 'string' },
+        namespace: { type: 'string' },
+        start: { type: 'string' },
+        entity_id: { type: 'string' },
+        query: { type: 'string' },
+        max_depth: { type: 'integer', minimum: 0, maximum: 12 },
+        limit: { type: 'integer', minimum: 1, maximum: 500 },
+        direction: { type: 'string' },
+      },
+      required: ['agent_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_cluster_memories',
+    description: 'Group active namespace-fenced memories by semantic proximity and return committed centroid fingerprints.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundlePath: { type: 'string' },
+        agent_id: { type: 'string' },
+        swarm_id: { type: 'string' },
+        namespace: { type: 'string' },
+        threshold: { type: 'number', minimum: 0, maximum: 1 },
+        max_clusters: { type: 'integer', minimum: 1, maximum: 100 },
+      },
+      required: ['agent_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_swarm_sync',
+    description: 'Create or validate an opt-in local gossip simulation using Merkle diffs; no network transmission occurs and raw content is excluded by default.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundlePath: { type: 'string' },
+        agent_id: { type: 'string' },
+        swarm_id: { type: 'string' },
+        namespace: { type: 'string' },
+        snapshot: { type: 'object' },
+        apply: { type: 'boolean' },
+        include_content: { type: 'boolean' },
+        allow_content: { type: 'boolean' },
+      },
+      required: ['agent_id'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'enigma_immune_ingress',
+    description: 'Scan MCP-supplied memory candidate objects and return a public-safe immune quarantine report with opaque refs only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        candidate: { type: 'object' },
+        candidates: { type: 'array', items: { type: 'object' } },
+        generated_at: { type: 'string' },
+        now: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+  },
   {
     name: 'enigma_meter_usage',
     description: 'Create content-minimized memory usage events or aggregate supplied usage events without raw prompts or provider responses.',
@@ -546,9 +1270,30 @@ export const toolDescriptors = [
       additionalProperties: false,
     },
   },
+  // NOTE: enigma_verify_erasure_attestation is intentionally NOT exposed as an MCP
+  // tool. The hardware path pins only the chain root and trusts the leaf public key
+  // without verifying leaf/intermediate signatures, and the TPM path allowlists a
+  // forgeable issuer string — an attacker could obtain valid:true with their own
+  // key. The exported function remains for internal/direct use until real chain +
+  // quote validation lands.
+  {
+    name: 'enigma_nullifier_record_tombstone',
+    description: 'Build an owner-signed Solana record_revocation instruction for a registered Enigma commitment. Returns complete ordered account metas and instruction data; the owner must sign. Records protocol-level revocation/non-use only — not physical deletion of plaintext, backups, or external copies.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        commitment: { type: 'string', pattern: '^(0x)?[0-9a-fA-F]{64}$' },
+        nullifierHash: { type: 'string', pattern: '^(0x)?[0-9a-fA-F]{64}$' },
+        ownerPubkey: { type: 'string', description: 'Base58 Solana public key of the commitment owner (required signer)' },
+      },
+      required: ['commitment', 'nullifierHash', 'ownerPubkey'],
+      additionalProperties: false,
+    },
+  },
 ];
 
 const PASSPORT_SUMMARY_RESOURCE_URI = 'enigma://passport/summary';
+const PRIVATE_SESSION_HANDOFF_RESOURCE_URI = PRIVATE_SESSION_RESOURCE_URI;
 const STANDARD_MEMORY_PROMPT_NAME = 'enigma_standard_memory_prompt';
 
 export const resourceDescriptors = [
@@ -558,6 +1303,12 @@ export const resourceDescriptors = [
     description: 'MCP-safe Passport and Vault metadata for the local Enigma bundle. Raw memory plaintext is never exposed.',
     mimeType: 'application/json',
   },
+  {
+    uri: PRIVATE_SESSION_HANDOFF_RESOURCE_URI,
+    name: 'Enigma Private Session Handoff',
+    description: 'Enigma-branded MCP App handoff. The host sees only non-sensitive handoff metadata; the actual prompt is typed in the local Enigma workspace.',
+    mimeType: 'text/html;profile=mcp-app',
+  },
 ];
 
 export const promptDescriptors = [
@@ -580,16 +1331,41 @@ export const promptDescriptors = [
 ];
 
 function bundlePath(input = {}) {
-  return resolve(String(input.bundlePath ?? input.bundle_path ?? DEFAULT_BUNDLE));
+  const raw = input.bundlePath ?? input.bundle_path ?? input.bundle ?? process.env.ENIGMA_BUNDLE ?? DEFAULT_BUNDLE;
+  return resolve(String(raw));
 }
 
-async function readJson(path) {
-  return JSON.parse(await readFile(path, 'utf8'));
+function bundlePassphrase(input = {}) {
+  const value = input.passphrase ?? input.passPhrase ?? process.env.ENIGMA_PASSPHRASE ?? undefined;
+  if (value !== undefined && String(value).trim().length === 0) throw new Error('ENIGMA_PASSPHRASE is empty');
+  return value === undefined ? undefined : String(value);
 }
 
-async function writeJson(path, value) {
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+function bundleInsecureDevMode(input = {}) {
+  if (input[REMOTE_SECURE_VAULT] === true) return false;
+  return input.insecureDevMode === true
+    || input.insecure_dev_mode === true
+    || ['1', 'true'].includes(String(process.env.ENIGMA_INSECURE_DEV_MODE ?? '').toLowerCase());
+}
+
+function bundleCredentials(input = {}) {
+  const passphrase = bundlePassphrase(input);
+  const insecureDevMode = bundleInsecureDevMode(input);
+  if (passphrase === undefined && !insecureDevMode) {
+    throw new Error('Persistent MCP vault access requires ENIGMA_PASSPHRASE unless ENIGMA_INSECURE_DEV_MODE=1 is explicitly enabled.');
+  }
+  return {
+    passphrase,
+    insecureDevMode,
+    allowOldEpochReads: input.allowOldEpochReads ?? input.allow_old_epoch_reads,
+    checkpointProvider: input.checkpointProvider ?? configuredCheckpointProvider,
+    requireExternalCheckpoint: input.requireExternalCheckpoint === true
+      || process.env.ENIGMA_REQUIRE_EXTERNAL_CHECKPOINT === '1',
+  };
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
 }
 
 async function fileExists(path) {
@@ -602,50 +1378,89 @@ async function fileExists(path) {
   }
 }
 
-function reviveVault(stored) {
-  if (stored.schema !== 'enigma.vault_bundle.v1') throw new Error(`Unsupported Enigma bundle schema: ${stored.schema ?? '<missing>'}`);
-  const signingKeyPair = stored.keyring?.privateKey
-    ? { key_id: stored.keyring.signer?.key_id, publicKey: stored.keyring.publicKey, privateKey: stored.keyring.privateKey }
-    : undefined;
-  const vault = createVault({
-    vault_id: stored.vault?.vault_id,
-    tenant_id: stored.vault?.tenant_id,
-    subject_id: stored.vault?.subject_id,
-    actor_id: stored.vault?.actor_id,
-    policy_id: stored.vault?.policy_id,
-    vault_key: stored.keyring?.vault_key_b64,
-    address_key: stored.keyring?.address_key_b64,
-    signingKeyPair,
-    now: stored.vault?.created_at,
+async function loadState(path, input = {}) {
+  const credentials = bundleCredentials(input);
+  const loaded = await readJsonFileWithRevision(path, credentials);
+  const cacheKey = resolve(String(path));
+  const authTag = credentialCacheTag(credentials);
+  const cached = unlockedVaultCache.get(cacheKey);
+  const policyMatches = credentials.allowOldEpochReads === undefined
+    || cached?.vault?.allowOldEpochReads === credentials.allowOldEpochReads;
+  if (cached?.revision === loaded.revision && cached.authTag === authTag && policyMatches) {
+    unlockedVaultCache.delete(cacheKey);
+    unlockedVaultCache.set(cacheKey, cached);
+    return { ...cached, stored: loaded.value, revision: loaded.revision };
+  }
+  if (cached) invalidateCachedVault(cacheKey);
+  const imported = importBundle({
+    bundle: loaded.value,
+    ...credentials,
+    strict: true,
+    recordImport: false,
   });
-  if (stored.keyring?.signer) vault.signer = stored.keyring.signer;
-  vault.created_at = stored.vault?.created_at ?? vault.created_at;
-  vault.updated_at = stored.vault?.updated_at ?? vault.updated_at;
-  vault.sequence = Number.isInteger(stored.vault?.sequence) ? stored.vault.sequence : 0;
-  vault.events = Array.isArray(stored.events) ? stored.events : [];
-  vault.receipts = Array.isArray(stored.receipts) ? stored.receipts : [];
-  vault.memories = new Map((stored.memory_objects ?? []).map((record) => [record.memory_addr, { ...record }]));
-  vault.activeAddresses = new Set(stored.active_memory_addresses ?? []);
-  vault.tombstones = new Map((stored.tombstones ?? []).map((tombstone) => [tombstone.memory_addr, tombstone]));
-  const roots = vault.__computeRoots();
-  vault.active_set_root = roots.active_set_root;
-  vault.receipt_log_root = roots.receipt_log_root;
-  return vault;
-}
-
-async function loadState(path) {
-  const stored = await readJson(path);
-  const vault = reviveVault(stored);
-  return { stored, vault, passport: createPassport({ vault }) };
+  const vault = imported.vault;
+  const state = {
+    stored: loaded.value,
+    revision: loaded.revision,
+    vault,
+    passport: createPassport({ vault }),
+    verified: imported.verified,
+    authTag,
+  };
+  cacheUnlockedVault(cacheKey, state);
+  return state;
 }
 
-async function persistState(path, vault) {
-  const exported = exportBundle({ vault, includePlaintext: false });
+async function persistState(path, vault, input = {}) {
+  if (input.lockHeld !== true) {
+    return withBundleFileLock(path, async () => {
+      const expectedRevision = Object.prototype.hasOwnProperty.call(input, 'expectedRevision')
+        ? input.expectedRevision
+        : (await fileExists(path) ? (await readJsonFileWithRevision(path, bundleCredentials(input))).revision : null);
+      return persistState(path, vault, { ...input, lockHeld: true, expectedRevision });
+    });
+  }
+  const credentials = bundleCredentials(input);
+  const exported = exportBundle({ vault, passphrase: credentials.passphrase, includePlaintext: false });
   const bundle = exported.bundle ?? exported;
-  await writeJson(path, bundle);
+  const persisted = await writeJsonFileAtomic(path, bundle, {
+    ...(Object.prototype.hasOwnProperty.call(input, 'expectedRevision')
+      ? { expectedRevision: input.expectedRevision }
+      : {}),
+    checkpointProvider: credentials.checkpointProvider,
+    requireExternalCheckpoint: credentials.requireExternalCheckpoint,
+  });
+  const state = {
+    stored: bundle,
+    revision: persisted.revision,
+    vault,
+    passport: createPassport({ vault }),
+    verified: true,
+    authTag: credentialCacheTag(credentials),
+  };
+  cacheUnlockedVault(path, state);
+  Object.defineProperty(bundle, '__revision', { value: persisted.revision, enumerable: false });
   return bundle;
 }
 
+async function withVaultTransaction(path, input, operation) {
+  return withBundleFileLock(path, async () => {
+    const state = await loadState(path, input);
+    try {
+      const result = await operation(state);
+      const bundle = await persistState(path, state.vault, {
+        ...input,
+        lockHeld: true,
+        expectedRevision: state.revision,
+      });
+      return { ...state, revision: bundle.__revision, result, bundle };
+    } catch (error) {
+      invalidateCachedVault(path);
+      throw error;
+    }
+  });
+}
+
 function bundleSummary(path, bundle, created) {
   return {
     ok: true,
@@ -681,7 +1496,11 @@ function inputWithBundlePath(params = {}) {
   } catch {
     // Invalid or relative resource identifiers are rejected by the resource handler.
   }
-  return requestedPath === undefined ? { uri } : { uri, bundlePath: requestedPath };
+  return {
+    uri,
+    ...(requestedPath === undefined ? {} : { bundlePath: requestedPath }),
+    ...(params.insecureDevMode === true ? { insecureDevMode: true } : {}),
+  };
 }
 
 function passportFromBundle(bundle) {
@@ -750,7 +1569,7 @@ export async function enigma_passport_summary_resource(input = {}) {
     throw new Error(`Unknown Enigma resource: ${uri ?? '<missing>'}`);
   }
   const path = bundlePath(options);
-  const bundle = await readJson(path);
+  const { stored: bundle } = await loadState(path, options);
   return {
     contents: [
       {
@@ -762,6 +1581,162 @@ export async function enigma_passport_summary_resource(input = {}) {
   };
 }
 
+
+function privateSessionWidgetHtml() {
+  const url = privateSessionUrl();
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Enigma private session</title>
+  <style>
+    :root{color-scheme:dark;font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:#0a0908;color:#f4f2ef}
+    *{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px;background:radial-gradient(circle at 84% 0,rgba(255,122,26,.15),transparent 24rem),#0a0908}
+    main{width:min(620px,100%);padding:30px;border:1px solid rgba(255,255,255,.14);border-radius:18px;background:rgba(20,17,14,.92);box-shadow:inset 0 1px rgba(255,255,255,.07),0 24px 64px rgba(0,0,0,.45)}
+    .eyebrow{font:600 11px ui-monospace,monospace;letter-spacing:.18em;color:#ff8b3d}.mark{display:inline-block;width:8px;height:8px;margin-right:8px;border-radius:50%;background:#ff7a1a}
+    h1{max-width:14ch;margin:14px 0 10px;font-size:clamp(30px,7vw,52px);line-height:.98;letter-spacing:-.05em}p{max-width:58ch;color:#b9b6b1;font-size:14px;line-height:1.6}
+    a{display:inline-flex;margin-top:20px;padding:11px 15px;border-radius:9px;background:#ff7a1a;color:#1a0b02;font:700 11px ui-monospace,monospace;text-decoration:none;text-transform:uppercase}
+    section{display:grid;grid-template-columns:repeat(3,1fr);gap:1px;margin-top:26px;border:1px solid rgba(255,255,255,.12);background:rgba(255,255,255,.12)}
+    section div{padding:14px;background:#100e0c}small{display:block;color:#7d7a76;font:10px/1.45 ui-monospace,monospace}strong{display:block;margin-bottom:4px;font-size:12px}
+    @media(max-width:520px){section{grid-template-columns:1fr}}
+  </style>
+</head>
+<body>
+  <main>
+    <span class="eyebrow"><span class="mark"></span>ENIGMA / PRIVATE HANDOFF</span>
+    <h1>Type the private prompt inside Enigma.</h1>
+    <p>The actual prompt stays out of the MCP host chat. When you send it, the selected provider adapter receives the prepared request; Anchor Guard may mask supported patterns but is not semantic secrecy.</p>
+    <a href="${url}" target="_blank" rel="noreferrer">Open private workspace</a>
+    <section>
+      <div><strong>MCP host</strong><small>Handoff fact, route label, non-sensitive intent. No workspace prompt.</small></div>
+      <div><strong>Enigma workspace</strong><small>In-memory transcript and local context orchestration.</small></div>
+      <div><strong>Configured provider</strong><small>Receives adapter input, optionally pattern-redacted by Anchor Guard.</small></div>
+    </section>
+  </main>
+</body>
+</html>`;
+}
+
+function enigma_private_session_resource(input = {}) {
+  const uri = input.uri ?? PRIVATE_SESSION_HANDOFF_RESOURCE_URI;
+  if (String(uri) !== PRIVATE_SESSION_HANDOFF_RESOURCE_URI) {
+    throw new Error(`Unknown Enigma resource: ${uri ?? '<missing>'}`);
+  }
+  return {
+    contents: [{
+      uri: PRIVATE_SESSION_HANDOFF_RESOURCE_URI,
+      mimeType: 'text/html;profile=mcp-app',
+      text: privateSessionWidgetHtml(),
+    }],
+  };
+}
+
+export async function enigma_private_handoff_health(input = {}) {
+  validateToolArguments('enigma_private_handoff_health', input);
+  const origin = enigmaDesktopOrigin();
+  const startedAt = Date.now();
+  const protocolUrl = createPrivateSessionProtocolUrl();
+  try {
+    const response = await fetch(`${origin}/api/health`, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+      redirect: 'error',
+      signal: AbortSignal.timeout(1_500),
+    });
+    const body = await response.json();
+    const reachable = response.ok
+      && body?.ok === true
+      && body?.schema === 'enigma.desktop.health.v1'
+      && body?.service === 'enigma-desktop'
+      && typeof body?.instanceId === 'string';
+    return {
+      schema: 'enigma.private_handoff_health.v1',
+      reachable,
+      origin,
+      latencyMs: Date.now() - startedAt,
+      desktop: reachable ? body : null,
+      protocolUrl,
+      directProbeConfigured: Boolean(process.env.ENIGMA_DESKTOP_URL),
+      privateSessionResource: PRIVATE_SESSION_HANDOFF_RESOURCE_URI,
+      ...(reachable ? {} : { reason: 'invalid_enigma_health_schema' }),
+    };
+  } catch {
+    return {
+      schema: 'enigma.private_handoff_health.v1',
+      reachable: false,
+      origin,
+      latencyMs: Date.now() - startedAt,
+      desktop: null,
+      protocolUrl,
+      directProbeConfigured: Boolean(process.env.ENIGMA_DESKTOP_URL),
+      privateSessionResource: PRIVATE_SESSION_HANDOFF_RESOURCE_URI,
+      action: 'Launch the Enigma desktop app through the enigma:// protocol. Set ENIGMA_DESKTOP_URL only for a known CLI host.',
+    };
+  }
+}
+
+export function enigma_routing_contract(input = {}) {
+  validateToolArguments('enigma_routing_contract', input);
+  return {
+    schema: 'enigma.private_routing_contract.v1',
+    decision: {
+      sensitiveOrPrivate: 'Call enigma_start_private_session with a non-sensitive intent label only.',
+      alreadyHostVisible: 'Use normal Enigma memory tools only when the user accepts that the host can inspect the supplied text.',
+      actualPrivatePrompt: 'The user types it inside Enigma to keep it out of the MCP host chat; the configured provider still receives prepared adapter input.',
+    },
+    hostVisible: [
+      'Messages typed into the host chat.',
+      'The fact that an Enigma private session was requested.',
+      'Non-sensitive intent and model labels passed to the handoff tool.',
+      'Any text explicitly passed to ordinary MCP tool arguments.',
+    ],
+    keptOutOfMcpHost: [
+      'The prompt typed after the Enigma workspace opens.',
+      'The in-memory workspace transcript until refresh or explicit clearing.',
+      'The provider response rendered inside the workspace.',
+    ],
+    providerVisible: [
+      'The prompt and retrieved context prepared for the selected adapter.',
+      'Anchor Guard can mask documented patterns but does not detect arbitrary sensitive prose.',
+    ],
+    claims: {
+      hostChatInvisible: false,
+      privateHandoffAvailable: true,
+      promptRelayIsPrivateFromHost: false,
+      workspacePromptReturnedToMcpHost: false,
+      configuredProviderReceivesAdapterInput: true,
+      configuredProviderInvisible: false,
+    },
+  };
+}
+
+export function enigma_start_private_session(input = {}) {
+  input = validateToolArguments('enigma_start_private_session', input);
+  const intent = input.intent?.trim() || 'private question';
+  const model = input.model?.trim() || null;
+  return {
+    schema: 'enigma.private_session_handoff.v1',
+    url: privateSessionUrl({ intent, ...(model ? { model } : {}) }),
+    intent,
+    model,
+    resourceUri: PRIVATE_SESSION_HANDOFF_RESOURCE_URI,
+    embedEnabled: true,
+    hostBoundary: 'The workspace keeps the prompt out of the MCP host chat. The configured provider receives Enigma-prepared adapter input.',
+    providerBoundary: 'Anchor Guard may mask email, wallet, IPv4, formatted phone, and base58 patterns. It does not make arbitrary sensitive prose invisible to the configured provider.',
+    instructionsForHost: [
+      'Do not ask the user to paste the sensitive prompt into the host chat.',
+      'Do not place the sensitive prompt in an MCP tool argument.',
+      'Open the Enigma private session and let the user type there.',
+    ],
+    instructionsForUser: [
+      'Open the Enigma private workspace.',
+      'Choose a configured route if needed.',
+      'Type the actual private prompt inside Enigma.',
+      'The configured provider receives the prepared adapter input when you send.',
+    ],
+  };
+}
 export function enigma_standard_memory_prompt(input = {}) {
   const args = input?.arguments && typeof input.arguments === 'object' && !Array.isArray(input.arguments)
     ? input.arguments
@@ -788,66 +1763,140 @@ export function enigma_standard_memory_prompt(input = {}) {
   };
 }
 
+function requireInferenceRuntime(capability) {
+  if (!configuredInferenceRuntime || typeof configuredInferenceRuntime[capability] !== 'object') {
+    throw new Error(`Enigma ${capability} inference runtime is not configured`);
+  }
+  return configuredInferenceRuntime;
+}
+
+export async function enigma_complete(input = {}) {
+  input = validateToolArguments('enigma_complete', input);
+  const runtime = requireInferenceRuntime('chat');
+  return runtime.chat.complete({
+    messages: input.messages,
+    model: input.model || 'enigma-auto',
+    privacyMode: input.privacy_mode || 'smart',
+    temperature: input.temperature,
+    maxTokens: input.max_tokens,
+    reasoningEffort: input.reasoning_effort,
+    webSearch: input.web_search === true,
+    requirePrivateRoute: input.require_private_route === true,
+    stream: false,
+  });
+}
+
+export async function enigma_generate_image(input = {}) {
+  input = validateToolArguments('enigma_generate_image', input);
+  const runtime = requireInferenceRuntime('images');
+  return runtime.images.generate({
+    prompt: input.prompt,
+    model: input.model,
+    negativePrompt: input.negative_prompt,
+    width: input.width,
+    height: input.height,
+    steps: input.steps,
+    cfgScale: input.cfg_scale,
+    variants: input.variants,
+    format: input.format,
+    seed: input.seed,
+  });
+}
+
+export async function enigma_x402_execute(input = {}) {
+  input = validateToolArguments('enigma_x402_execute', input);
+  if (!configuredX402Client) throw new Error('Enigma x402 execution client is not configured');
+  const headers = { ...(input.headers || {}) };
+  const body = input.body === undefined
+    ? undefined
+    : typeof input.body === 'string'
+      ? input.body
+      : JSON.stringify(input.body);
+  if (body !== undefined && !Object.keys(headers).some((name) => name.toLowerCase() === 'content-type')) {
+    headers['Content-Type'] = 'application/json';
+  }
+  const execution = await configuredX402Client(input.url, { method: input.method || 'GET', headers, body });
+  const maximum = input.max_response_bytes || 262144;
+  const declared = Number(execution.response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > maximum) {
+    await execution.response.body?.cancel?.();
+    throw new Error('x402 resource response exceeds the configured limit');
+  }
+  const bytes = Buffer.from(await execution.response.arrayBuffer());
+  if (bytes.length > maximum) throw new Error('x402 resource response exceeds the configured limit');
+  const contentType = execution.response.headers.get('content-type') || 'application/octet-stream';
+  let responseBody = bytes.toString('utf8');
+  if (contentType.includes('application/json')) {
+    try { responseBody = JSON.parse(responseBody); } catch { throw new Error('x402 resource returned invalid JSON'); }
+  }
+  return {
+    schema: 'enigma.x402_execution.v1',
+    status: execution.response.status,
+    contentType,
+    body: responseBody,
+    settlement: execution.settlement,
+    paymentRequired: execution.paymentRequired,
+  };
+}
+
 export async function enigma_init(input = {}) {
   input = validateToolArguments('enigma_init', input);
   const path = bundlePath(input);
-  if (await fileExists(path)) {
-    const bundle = await readJson(path);
-    if (bundle.schema !== 'enigma.vault_bundle.v1') throw new Error(`Unsupported Enigma bundle schema: ${bundle.schema ?? '<missing>'}`);
-    return bundleSummary(path, bundle, false);
-  }
-
-  const vault = createVault({
-    tenant_id: input.tenant_id,
-    subject_id: input.subject_id,
-    actor_id: input.actor_id,
-    policy_id: input.policy_id,
+  const credentials = bundleCredentials(input);
+  return withBundleFileLock(path, async () => {
+    if (await fileExists(path)) {
+      const state = await loadState(path, input);
+      return bundleSummary(path, state.stored, false);
+    }
+    const vault = createVault({
+      tenant_id: input.tenant_id,
+      subject_id: input.subject_id,
+      actor_id: input.actor_id,
+      policy_id: input.policy_id,
+      passphrase: credentials.passphrase,
+    });
+    const bundle = await persistState(path, vault, { ...input, lockHeld: true, expectedRevision: null });
+    return bundleSummary(path, bundle, true);
   });
-  const bundle = await persistState(path, vault);
-  return bundleSummary(path, bundle, true);
 }
 
 export async function enigma_remember(input = {}) {
   input = validateToolArguments('enigma_remember', input);
   const path = bundlePath(input);
-  const { vault, passport } = await loadState(path);
-  const result = remember({
+  const { result } = await withVaultTransaction(path, input, ({ vault, passport }) => remember({
     vault,
     passport,
     text: input.text,
     purpose: input.purpose ?? 'mcp_memory',
     purpose_tags: Array.isArray(input.tags) ? input.tags : [],
     metadata: input.metadata ?? {},
-  });
-  await persistState(path, vault);
+  }));
   return { ok: true, memory_addr: result.memory_addr, receipt_id: result.receipt?.receipt_id };
 }
 
 export async function enigma_search(input = {}) {
   input = validateToolArguments('enigma_search', input);
   const path = bundlePath(input);
-  const { vault, passport } = await loadState(path);
-  if (input.memory_addr) {
-    const result = recall({ vault, passport, memory_addr: input.memory_addr, purpose: input.purpose ?? 'mcp_search' });
-    await persistState(path, vault);
-    return result;
-  }
-  const pack = compileContextPack({
-    vault,
-    passport,
-    query: input.query ?? '',
-    purpose: input.purpose ?? 'mcp_search',
-    limit: Number(input.limit ?? 8),
+  const { result } = await withVaultTransaction(path, input, ({ vault, passport }) => {
+    if (input.memory_addr) {
+      return recall({ vault, passport, memory_addr: input.memory_addr, purpose: input.purpose ?? 'mcp_search' });
+    }
+    const pack = compileContextPack({
+      vault,
+      passport,
+      query: input.query ?? '',
+      purpose: input.purpose ?? 'mcp_search',
+      limit: Number(input.limit ?? 8),
+    });
+    return { memories: pack.memories ?? [], receipts: pack.retrieval_receipts ?? pack.receipts ?? [] };
   });
-  await persistState(path, vault);
-  return { memories: pack.memories ?? [], receipts: pack.retrieval_receipts ?? pack.receipts ?? [] };
+  return result;
 }
 
 export async function enigma_context_pack(input = {}) {
   input = validateToolArguments('enigma_context_pack', input);
   const path = bundlePath(input);
-  const { vault, passport } = await loadState(path);
-  const pack = compileContextPack({
+  const { result } = await withVaultTransaction(path, input, ({ vault, passport }) => compileContextPack({
     vault,
     passport,
     query: input.query ?? '',
@@ -858,29 +1907,107 @@ export async function enigma_context_pack(input = {}) {
     currency: input.currency,
     limit: Number(input.limit ?? 8),
     memory_addresses: input.memory_addresses,
-  });
-  await persistState(path, vault);
-  return pack;
+  }));
+  return result;
 }
 
 export async function enigma_delete(input = {}) {
   input = validateToolArguments('enigma_delete', input);
   const path = bundlePath(input);
-  const { vault, passport } = await loadState(path);
-  const result = deleteMemory({
+  const { result } = await withVaultTransaction(path, input, ({ vault, passport }) => deleteMemory({
     vault,
     passport,
     memory_addr: input.memory_addr,
     reason: input.reason ?? 'mcp_delete',
-  });
-  await persistState(path, vault);
+  }));
   return { ok: true, memory_addr: result.memory_addr, receipt_id: result.receipt?.receipt_id };
 }
 
+export async function enigma_vault_rotate(input = {}) {
+  input = validateToolArguments('enigma_vault_rotate', input);
+  const path = bundlePath(input);
+  const { result } = await withVaultTransaction(path, input, ({ vault }) => rotateContentKey({
+    vault,
+    key_id: input.key_id,
+  }));
+  return { ok: true, operation: 'key_rotate', ...result };
+}
+
+export async function enigma_vault_seal(input = {}) {
+  input = validateToolArguments('enigma_vault_seal', input);
+  const path = bundlePath(input);
+  const { result } = await withVaultTransaction(path, input, ({ vault }) => sealContentKeyEpoch({
+    vault,
+    epoch: input.epoch,
+  }));
+  return { ok: true, operation: 'key_seal', ...result };
+}
+
+export async function enigma_vault_reset(input = {}) {
+  input = validateToolArguments('enigma_vault_reset', input);
+  const path = bundlePath(input);
+  const { result } = await withVaultTransaction(path, input, ({ vault }) => resetVaultContentKeys({
+    vault,
+    key_id: input.key_id,
+  }));
+  return { ok: true, operation: 'key_reset', ...result };
+}
+
 export async function enigma_verify_receipts(input = {}) {
   input = validateToolArguments('enigma_verify_receipts', input);
-  const bundle = input.bundle ?? await readJson(bundlePath(input));
-  return verifyBundle(bundle);
+  if (input.bundle) return verifyBundle(input.bundle);
+  const path = bundlePath(input);
+  bundleCredentials(input);
+  const stored = await readJson(path);
+  const report = verifyBundle(stored);
+  if (!report.ok) return report;
+  await loadState(path, input);
+  return report;
+}
+
+async function activeSwarmAtoms(input) {
+  const path = bundlePath(input);
+  if (!(await fileExists(path))) return [];
+  const { result } = await withVaultTransaction(path, input, ({ vault, passport }) => {
+    const atoms = [];
+    for (const memoryAddr of [...vault.activeAddresses].sort()) {
+      const recalled = recall({
+        vault,
+        passport,
+        memory_addr: memoryAddr,
+        purpose: 'mcp_swarm_context',
+      });
+      const { content_ciphertext: ignoredCiphertext, ...memory } = recalled.memory;
+      atoms.push({ ...memory, content: recalled.content });
+    }
+    return atoms;
+  });
+  return result;
+}
+
+export async function enigma_swarm_register_agent(input = {}) {
+  input = validateToolArguments('enigma_swarm_register_agent', input);
+  return routeSwarmRegisterAgent(input);
+}
+
+export async function enigma_graph_query(input = {}) {
+  input = validateToolArguments('enigma_graph_query', input);
+  return routeGraphQuery({ ...input, atoms: await activeSwarmAtoms(input) });
+}
+
+export async function enigma_cluster_memories(input = {}) {
+  input = validateToolArguments('enigma_cluster_memories', input);
+  return routeClusterMemories({ ...input, atoms: await activeSwarmAtoms(input) });
+}
+
+export async function enigma_swarm_sync(input = {}) {
+  input = validateToolArguments('enigma_swarm_sync', input);
+  return routeSwarmSync({ ...input, atoms: await activeSwarmAtoms(input) });
+}
+
+export async function enigma_immune_ingress(input = {}) {
+  input = validateToolArguments('enigma_immune_ingress', input);
+  return createMcpImmuneIngressReport(input);
 }
 
 export async function enigma_meter_usage(input = {}) {
@@ -943,13 +2070,130 @@ export async function enigma_settlement_batch(input = {}) {
 }
 
 
+export async function enigma_vault_create_record(input = {}) {
+  input = validateToolArguments('enigma_vault_create_record', input);
+  return defaultEnclave.createRecord(input.plaintext, input.metadata || {});
+}
+
+export async function enigma_vault_zeroize_record(input = {}) {
+  input = validateToolArguments('enigma_vault_zeroize_record', input);
+  return defaultEnclave.zeroizeRecord(input.recordId);
+}
+
+export async function enigma_verify_erasure_attestation(input = {}) {
+  input = validateToolArguments('enigma_verify_erasure_attestation', input);
+  return AttestationVerifier.verify(input.attestation, {
+    // Simulated attestations are developer-mode only: must be explicitly enabled.
+    allowSimulated: input.allowSimulated ?? false,
+    allowlistedSimulatedKeyPem: defaultEnclave.publicKeyPem,
+    expectedPcr: input.expectedPcr,
+  });
+}
+
+export async function enigma_nullifier_record_tombstone(input = {}) {
+  input = validateToolArguments('enigma_nullifier_record_tombstone', input);
+  const { PublicKey } = await import('@solana/web3.js');
+
+  const programId = 'E18KZR1Jq8fG3FFACpoHsE21ME3t1ftKPEwXL7cFWkoZ';
+  const programKey = new PublicKey(programId);
+  // Strict 32-byte hex validation — no padding, no truncation, no silent mutation.
+  const HEX32_RE = /^(0x)?[0-9a-fA-F]{64}$/;
+  if (!HEX32_RE.test(input.commitment)) {
+    throw new Error('enigma_nullifier_record_tombstone: commitment must be exactly 32 bytes of hex (64 hex chars, optional 0x prefix)');
+  }
+  if (!HEX32_RE.test(input.nullifierHash)) {
+    throw new Error('enigma_nullifier_record_tombstone: nullifierHash must be exactly 32 bytes of hex (64 hex chars, optional 0x prefix)');
+  }
+  const commitmentClean = input.commitment.replace(/^0x/, '');
+  const nullifierClean = input.nullifierHash.replace(/^0x/, '');
+
+  const commitmentBytes = Buffer.from(commitmentClean, 'hex');
+  const nullifierBytes = Buffer.from(nullifierClean, 'hex');
+  if (commitmentBytes.length !== 32 || nullifierBytes.length !== 32) {
+    throw new Error('enigma_nullifier_record_tombstone: decoded values must be exactly 32 bytes');
+  }
+
+  // Owner is the required Signer; the tombstone PDA is derived from owner + commitment.
+  let ownerKey;
+  try {
+    ownerKey = new PublicKey(input.ownerPubkey);
+  } catch {
+    throw new Error('enigma_nullifier_record_tombstone: ownerPubkey must be a valid base58 public key');
+  }
+
+  const [commitmentPda, commitmentBump] = PublicKey.findProgramAddressSync(
+    [Buffer.from('commitment'), ownerKey.toBuffer(), commitmentBytes],
+    programKey,
+  );
+  const [tombstonePda, tombstoneBump] = PublicKey.findProgramAddressSync(
+    [Buffer.from('tombstone'), ownerKey.toBuffer(), commitmentBytes],
+    programKey,
+  );
+  const [registryPda, registryBump] = PublicKey.findProgramAddressSync(
+    [Buffer.from('nullifier_registry')],
+    programKey,
+  );
+
+  // Anchor discriminator for global:record_revocation (owner-signed revocation record;
+  // no PCR/attestation framing — physical deletion is out of scope).
+  const discriminator = Buffer.from([108, 45, 14, 21, 217, 230, 163, 121]);
+  const instructionData = Buffer.concat([
+    discriminator,
+    commitmentBytes,
+    nullifierBytes,
+  ]);
+
+  // Ordered account metas matching RecordRevocation (commitment_record, tombstone,
+  // registry, owner, system). The commitment must be registered first — revocation
+  // flips its is_nullified flag on-chain.
+  const accounts = [
+    { pubkey: commitmentPda.toBase58(), isSigner: false, isWritable: true, role: 'commitment_record', bump: commitmentBump },
+    { pubkey: tombstonePda.toBase58(), isSigner: false, isWritable: true, role: 'tombstone', bump: tombstoneBump },
+    { pubkey: registryPda.toBase58(), isSigner: false, isWritable: true, role: 'registry', bump: registryBump },
+    { pubkey: ownerKey.toBase58(), isSigner: true, isWritable: true, role: 'owner' },
+    { pubkey: '11111111111111111111111111111111', isSigner: false, isWritable: false, role: 'system_program' },
+  ];
+
+  return {
+    programId,
+    instruction: 'record_revocation',
+    discriminator: Array.from(discriminator),
+    accounts,
+    instructionDataHex: instructionData.toString('hex'),
+    commitment: input.commitment,
+    nullifierHash: input.nullifierHash,
+    ownerPubkey: ownerKey.toBase58(),
+    requiresOwnerSignature: true,
+    requiresRegisteredCommitment: true,
+    timestamp: new Date().toISOString(),
+    broadcastReady: true,
+  };
+}
+
+
+// enigma_verify_erasure_attestation deliberately excluded from RPC handlers (see
+// toolDescriptors note above): hardware attestation verification is not yet safe.
 export const handlers = Object.freeze({
+  enigma_private_handoff_health,
+  enigma_routing_contract,
+  enigma_start_private_session,
+  enigma_complete,
+  enigma_generate_image,
+  enigma_x402_execute,
   enigma_init,
   enigma_remember,
   enigma_search,
   enigma_context_pack,
   enigma_delete,
+  enigma_vault_rotate,
+  enigma_vault_seal,
+  enigma_vault_reset,
   enigma_verify_receipts,
+  enigma_swarm_register_agent,
+  enigma_graph_query,
+  enigma_cluster_memories,
+  enigma_swarm_sync,
+  enigma_immune_ingress,
   enigma_meter_usage,
   enigma_settlement_job,
   enigma_settlement_capacity,
@@ -957,6 +2201,9 @@ export const handlers = Object.freeze({
   enigma_settlement_receipt,
   enigma_settlement_verify,
   enigma_settlement_batch,
+  enigma_vault_create_record,
+  enigma_vault_zeroize_record,
+  enigma_nullifier_record_tombstone,
 });
 
 function jsonRpcResult(id, result) {
@@ -987,6 +2234,28 @@ function toolHandler(name) {
 
 function toolCallContent(result, toolName) {
   const verificationFailed = (toolName === 'enigma_verify_receipts' || toolName === 'enigma_settlement_verify') && result && typeof result === 'object' && result.ok === false;
+  if (toolName === 'enigma_generate_image' && result && typeof result === 'object') {
+    const content = [];
+    const assets = (result.assets || []).map((asset, index) => {
+      const mimeType = `image/${asset.format === 'jpg' ? 'jpeg' : asset.format || 'webp'}`;
+      if (typeof asset.base64 === 'string') {
+        content.push({ type: 'image', data: asset.base64, mimeType });
+        return { index, format: asset.format, inline: true };
+      }
+      if (typeof asset.url === 'string' && asset.url.startsWith('data:')) {
+        const match = /^data:([^;,]+);base64,(.+)$/s.exec(asset.url);
+        if (match) {
+          content.push({ type: 'image', data: match[2], mimeType: match[1] });
+          return { index, format: asset.format, inline: true };
+        }
+      }
+      content.push({ type: 'text', text: `Generated image ${index + 1}: ${asset.url}` });
+      return { index, format: asset.format, url: asset.url };
+    });
+    const structuredContent = { ...result, assets };
+    content.unshift({ type: 'text', text: JSON.stringify(structuredContent) });
+    return { content, structuredContent, isError: false };
+  }
   return {
     content: [{ type: 'text', text: JSON.stringify(result ?? null) }],
     structuredContent: result ?? null,
@@ -1020,7 +2289,7 @@ function validateNoParams(params, method) {
   rejectAdditionalProperties(input, new Set(), `${method} params`);
 }
 
-async function handleSingleJsonRpcRequest(request) {
+async function handleSingleJsonRpcRequest(request, context = {}) {
   if (!isRequestObject(request)) return jsonRpcError(null, JSON_RPC_ERROR.INVALID_REQUEST, 'Invalid Request');
 
   const notification = !hasJsonRpcId(request);
@@ -1031,6 +2300,12 @@ async function handleSingleJsonRpcRequest(request) {
   if (request.jsonrpc !== JSONRPC_VERSION || typeof request.method !== 'string') {
     return jsonRpcError(id, JSON_RPC_ERROR.INVALID_REQUEST, 'Invalid Request');
   }
+  if (context.transport === 'streamable-http') {
+    const requiredScopes = requiredScopesForMcpPayload(request);
+    if (!context.principal || !Array.isArray(context.principal.scopes) || requiredScopes.some((scope) => !context.principal.scopes.includes(scope))) {
+      return notification ? undefined : jsonRpcError(id, JSON_RPC_ERROR.INVALID_REQUEST, 'Insufficient OAuth scope.', { requiredScopes });
+    }
+  }
 
   try {
     switch (request.method) {
@@ -1054,7 +2329,7 @@ async function handleSingleJsonRpcRequest(request) {
         return notification ? undefined : jsonRpcResult(id, {});
       case 'tools/list':
         validateNoParams(request.params, 'tools/list');
-        return notification ? undefined : jsonRpcResult(id, { tools: toolDescriptors });
+        return notification ? undefined : jsonRpcResult(id, { tools: context.transport === 'streamable-http' ? remoteToolDescriptors() : toolDescriptors });
       case 'resources/list':
         validateNoParams(request.params, 'resources/list');
         return notification ? undefined : jsonRpcResult(id, { resources: resourceDescriptors });
@@ -1063,11 +2338,32 @@ async function handleSingleJsonRpcRequest(request) {
         return notification ? undefined : jsonRpcResult(id, { resourceTemplates: [] });
       case 'resources/read': {
         const params = ensureParamsObject(request.params, 'resources/read');
-        rejectAdditionalProperties(params, new Set(['uri', 'bundlePath']), 'resources/read params');
+        rejectAdditionalProperties(params, new Set(['uri', 'bundlePath', 'insecureDevMode']), 'resources/read params');
         requireString(params, 'uri', 'resources/read params');
         optionalString(params, 'bundlePath', 'resources/read params');
-        if (normalizeResourceUri(params.uri) !== PASSPORT_SUMMARY_RESOURCE_URI) throw invalidParams('Unknown resource.');
-        const result = await enigma_passport_summary_resource(inputWithBundlePath(params));
+        optionalBoolean(params, 'insecureDevMode', 'resources/read params');
+        const normalizedUri = normalizeResourceUri(params.uri);
+        let result;
+        if (normalizedUri === PASSPORT_SUMMARY_RESOURCE_URI) {
+          result = await enigma_passport_summary_resource(await bindRemoteResourceInput(params, normalizedUri, context));
+        } else if (normalizedUri === PRIVATE_SESSION_HANDOFF_RESOURCE_URI) {
+          result = enigma_private_session_resource({ uri: normalizedUri });
+        } else {
+          throw invalidParams('Unknown resource.');
+        }
+        if (context.transport === 'streamable-http' && Array.isArray(result?.contents)) {
+          result = {
+            ...result,
+            contents: result.contents.map((content) => {
+              if (content?.mimeType !== 'application/json' || typeof content.text !== 'string') return content;
+              try {
+                return { ...content, text: JSON.stringify(sanitizeRemoteCustodyOutput(JSON.parse(content.text), context)) };
+              } catch {
+                return content;
+              }
+            }),
+          };
+        }
         return notification ? undefined : jsonRpcResult(id, result);
       }
       case 'prompts/list':
@@ -1087,9 +2383,11 @@ async function handleSingleJsonRpcRequest(request) {
         requireString(params, 'name', 'tools/call params');
         const handler = toolHandler(params.name);
         if (!handler) throw invalidParams('Unknown tool.');
-        const args = toolArguments(params.name, params);
+        const args = context.transport === 'streamable-http'
+          ? await bindRemoteToolArguments(params.name, params.arguments ?? {}, context)
+          : toolArguments(params.name, params);
         try {
-          const result = await handler(args);
+          const result = sanitizeRemoteCustodyOutput(await handler(args), context);
           return notification ? undefined : jsonRpcResult(id, toolCallContent(result, params.name));
         } catch (error) {
           return notification ? undefined : jsonRpcResult(id, toolCallError(error));
@@ -1105,13 +2403,13 @@ async function handleSingleJsonRpcRequest(request) {
   }
 }
 
-export async function handleJsonRpcRequest(request) {
-  if (!Array.isArray(request)) return handleSingleJsonRpcRequest(request);
+export async function handleJsonRpcRequest(request, context = {}) {
+  if (!Array.isArray(request)) return handleSingleJsonRpcRequest(request, context);
   if (request.length === 0) return jsonRpcError(null, JSON_RPC_ERROR.INVALID_REQUEST, 'Invalid Request');
 
   const responses = [];
   for (const item of request) {
-    const response = await handleSingleJsonRpcRequest(item);
+    const response = await handleSingleJsonRpcRequest(item, context);
     if (response !== undefined) responses.push(response);
   }
   return responses.length === 0 ? undefined : responses;
@@ -1165,12 +2463,25 @@ export default {
   resourceDescriptors,
   promptDescriptors,
   handlers,
+  enigma_private_handoff_health,
+  enigma_routing_contract,
+  enigma_start_private_session,
+  configureMcpInferenceRuntime,
+  configureMcpX402Client,
+  enigma_complete,
+  enigma_generate_image,
+  enigma_x402_execute,
   enigma_init,
   enigma_remember,
   enigma_search,
   enigma_context_pack,
   enigma_delete,
   enigma_verify_receipts,
+  enigma_swarm_register_agent,
+  enigma_graph_query,
+  enigma_cluster_memories,
+  enigma_swarm_sync,
+  enigma_immune_ingress,
   enigma_meter_usage,
   enigma_settlement_job,
   enigma_settlement_capacity,
@@ -1180,6 +2491,8 @@ export default {
   enigma_settlement_batch,
   enigma_passport_summary_resource,
   enigma_standard_memory_prompt,
+  createMcpImmuneIngressReport,
+  assertMcpImmuneIngressPublicSafe,
   handleJsonRpcRequest,
   startStdioServer,
 };