enigma-memory 0.1.17 → 0.1.22

package/packages/mcp-server/src/remote-http.js

@@ -0,0 +1,273 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { requiredScopesForMcpPayload } from './remote-policy.js';
+
+const JSON_CONTENT_TYPE = 'application/json';
+const SSE_CONTENT_TYPE = 'text/event-stream';
+const SUPPORTED_PROTOCOL_VERSIONS = new Set(['2024-11-05', '2025-03-26', '2025-06-18']);
+
+class HttpMcpError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = 'HttpMcpError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function integer(value, name, minimum, maximum, fallback) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new TypeError(`${name} must be an integer from ${minimum} through ${maximum}`);
+  }
+  return resolved;
+}
+
+function normalizeEndpoint(value) {
+  const endpoint = String(value || '/mcp');
+  if (!endpoint.startsWith('/') || endpoint.includes('?') || endpoint.includes('#') || endpoint.includes('..')) {
+    throw new TypeError('MCP endpoint must be an absolute path');
+  }
+  return endpoint.length > 1 ? endpoint.replace(/\/+$/, '') : endpoint;
+}
+
+function normalizeAllowedOrigins(values = []) {
+  if (!Array.isArray(values)) throw new TypeError('allowedOrigins must be an array');
+  return new Set(values.map((value) => {
+    const url = new URL(String(value));
+    if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+      throw new TypeError('allowed MCP origins must contain only scheme, host, and port');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname))) {
+      throw new TypeError('allowed MCP origins must use HTTPS outside localhost');
+    }
+    return url.origin;
+  }));
+}
+
+function requestUrl(request) {
+  const authority = request.headers.host || 'localhost';
+  return new URL(request.url || '/', `http://${authority}`);
+}
+
+function setSecurityHeaders(response, requestId) {
+  response.setHeader('Cache-Control', 'no-store, max-age=0');
+  response.setHeader('Cross-Origin-Resource-Policy', 'same-site');
+  response.setHeader('Referrer-Policy', 'no-referrer');
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.setHeader('X-Frame-Options', 'DENY');
+  response.setHeader('X-Enigma-Request-Id', requestId);
+}
+
+function setCorsHeaders(request, response, allowedOrigins) {
+  const origin = request.headers.origin;
+  if (!origin) return;
+  if (!allowedOrigins.has(origin)) throw new HttpMcpError(403, 'origin_denied', 'request origin is not allowed');
+  response.setHeader('Access-Control-Allow-Origin', origin);
+  response.setHeader('Access-Control-Allow-Credentials', 'false');
+  response.setHeader('Vary', 'Origin');
+}
+
+function writeJson(response, status, value) {
+  const body = JSON.stringify(value);
+  response.statusCode = status;
+  response.setHeader('Content-Type', `${JSON_CONTENT_TYPE}; charset=utf-8`);
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.end(body);
+}
+
+function writeSse(response, value) {
+  const body = `event: message\ndata: ${JSON.stringify(value)}\n\n`;
+  response.statusCode = 200;
+  response.setHeader('Content-Type', `${SSE_CONTENT_TYPE}; charset=utf-8`);
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.setHeader('Connection', 'close');
+  response.end(body);
+}
+
+async function readJsonBody(request, maxBodyBytes) {
+  const contentType = String(request.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase();
+  if (contentType !== JSON_CONTENT_TYPE) throw new HttpMcpError(415, 'unsupported_media_type', 'Content-Type must be application/json');
+  const declaredLength = Number(request.headers['content-length']);
+  if (Number.isFinite(declaredLength) && declaredLength > maxBodyBytes) {
+    request.resume();
+    throw new HttpMcpError(413, 'payload_too_large', 'MCP request body exceeds the configured limit');
+  }
+  const chunks = [];
+  let bytes = 0;
+  let tooLarge = false;
+  for await (const chunk of request) {
+    bytes += chunk.length;
+    if (bytes > maxBodyBytes) {
+      tooLarge = true;
+      continue;
+    }
+    chunks.push(chunk);
+  }
+  if (tooLarge) throw new HttpMcpError(413, 'payload_too_large', 'MCP request body exceeds the configured limit');
+  if (bytes === 0) throw new HttpMcpError(400, 'empty_body', 'MCP request body is required');
+  try {
+    return JSON.parse(Buffer.concat(chunks, bytes).toString('utf8'));
+  } catch {
+    throw new HttpMcpError(400, 'parse_error', 'MCP request body is not valid JSON');
+  }
+}
+
+function accepts(request, mediaType) {
+  const header = String(request.headers.accept || '*/*').toLowerCase();
+  return header.includes('*/*') || header.includes(mediaType);
+}
+
+function bearerChallenge(resourceMetadataUrl, details = {}) {
+  const parameters = [];
+  if (resourceMetadataUrl) parameters.push(`resource_metadata="${resourceMetadataUrl}"`);
+  if (details.error) parameters.push(`error="${details.error}"`);
+  if (details.scope) parameters.push(`scope="${details.scope}"`);
+  return parameters.length ? `Bearer ${parameters.join(', ')}` : 'Bearer';
+}
+
+
+export function createSubjectVaultResolver(options = {}) {
+  const root = resolve(String(options.root || ''));
+  if (!options.root) throw new TypeError('subject vault resolver requires an operator-controlled root');
+  const policyId = String(options.policyId || 'remote_oauth');
+  return async function resolveSubjectVault(principal) {
+    const subject = String(principal?.subject || '').trim();
+    const tenant = String(principal?.tenantId || principal?.tenant_id || 'default').trim();
+    const clientId = String(principal?.clientId || 'remote-mcp').trim();
+    if (!subject || subject.length > 512 || !tenant || tenant.length > 512) throw new Error('authenticated principal cannot be mapped to a vault');
+    const tenantRef = createHash('sha256').update(`tenant\\0${tenant}`).digest('hex');
+    const subjectRef = createHash('sha256').update(`subject\\0${tenant}\\0${subject}`).digest('hex');
+    const actorRef = createHash('sha256').update(`actor\\0${clientId}`).digest('hex');
+    const bundlePath = resolve(join(root, tenantRef, subjectRef, 'bundle.json'));
+    const relativePath = relative(root, bundlePath);
+    if (!relativePath || relativePath.startsWith('..') || isAbsolute(relativePath)) {
+      throw new Error('resolved subject vault escaped the configured root');
+    }
+    return Object.freeze({
+      bundlePath,
+      tenant_id: `tenant_${tenantRef}`,
+      subject_id: `subject_${subjectRef}`,
+      actor_id: `actor_${actorRef}`,
+      policy_id: policyId,
+    });
+  };
+}
+
+export function createStreamableHttpMcpHandler(options = {}) {
+  if (typeof options.rpcHandler !== 'function') throw new TypeError('rpcHandler is required');
+  if (typeof options.authorize !== 'function') throw new TypeError('authorize is required for remote MCP');
+  const endpoint = normalizeEndpoint(options.endpoint);
+  const maxBodyBytes = integer(options.maxBodyBytes, 'maxBodyBytes', 1_024, 8 * 1_024 * 1_024, 1_048_576);
+  const allowedOrigins = normalizeAllowedOrigins(options.allowedOrigins || []);
+  const resourceMetadataUrl = options.resourceMetadataUrl ? new URL(String(options.resourceMetadataUrl)).toString() : null;
+  const resolveVaultContext = typeof options.resolveVaultContext === 'function'
+    ? options.resolveVaultContext
+    : options.vaultRoot
+      ? createSubjectVaultResolver({ root: options.vaultRoot, policyId: options.vaultPolicyId })
+      : null;
+  if (!resolveVaultContext) throw new TypeError('remote MCP requires resolveVaultContext() or an operator-controlled vaultRoot');
+
+  return async function streamableHttpMcpHandler(request, response) {
+    const requestId = randomUUID();
+    setSecurityHeaders(response, requestId);
+    try {
+      const url = requestUrl(request);
+      if (url.pathname !== endpoint || url.search) throw new HttpMcpError(404, 'not_found', 'MCP endpoint not found');
+      setCorsHeaders(request, response, allowedOrigins);
+
+      if (request.method === 'OPTIONS') {
+        if (!request.headers.origin) throw new HttpMcpError(400, 'origin_required', 'CORS preflight requires Origin');
+        response.statusCode = 204;
+        response.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+        response.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, MCP-Protocol-Version');
+        response.setHeader('Access-Control-Max-Age', '600');
+        response.end();
+        return;
+      }
+      if (request.method !== 'POST') {
+        response.setHeader('Allow', 'POST, OPTIONS');
+        throw new HttpMcpError(405, 'method_not_allowed', 'stateless MCP accepts POST requests only');
+      }
+      if (request.headers['mcp-session-id']) {
+        throw new HttpMcpError(400, 'unexpected_session', 'this MCP endpoint is stateless and does not issue session identifiers');
+      }
+      const protocolVersion = request.headers['mcp-protocol-version'];
+      if (protocolVersion && !SUPPORTED_PROTOCOL_VERSIONS.has(String(protocolVersion))) {
+        throw new HttpMcpError(400, 'unsupported_protocol_version', 'unsupported MCP protocol version');
+      }
+      if (!accepts(request, JSON_CONTENT_TYPE) && !accepts(request, SSE_CONTENT_TYPE)) {
+        throw new HttpMcpError(406, 'not_acceptable', 'Accept must include application/json or text/event-stream');
+      }
+
+      let principal;
+      try {
+        principal = await options.authorize({
+          authorization: request.headers.authorization || null,
+          headers: request.headers,
+          method: request.method,
+          path: url.pathname,
+          requestId,
+        });
+      } catch {
+        principal = null;
+      }
+      if (!principal) {
+        response.setHeader('WWW-Authenticate', bearerChallenge(resourceMetadataUrl));
+        throw new HttpMcpError(401, 'invalid_token', 'a valid OAuth access token is required');
+      }
+      const principalScopes = new Set(Array.isArray(principal.scopes) ? principal.scopes : []);
+      if (!principalScopes.has('mcp:invoke')) {
+        response.setHeader('WWW-Authenticate', bearerChallenge(resourceMetadataUrl, { error: 'insufficient_scope', scope: 'mcp:invoke' }));
+        throw new HttpMcpError(403, 'insufficient_scope', 'OAuth token lacks the MCP invocation scope');
+      }
+
+      const payload = await readJsonBody(request, maxBodyBytes);
+      const requiredScopes = requiredScopesForMcpPayload(payload);
+      const missingScopes = requiredScopes.filter((scope) => !principalScopes.has(scope));
+      if (missingScopes.length) {
+        response.setHeader('WWW-Authenticate', bearerChallenge(resourceMetadataUrl, { error: 'insufficient_scope', scope: requiredScopes.join(' ') }));
+        throw new HttpMcpError(403, 'insufficient_scope', 'OAuth token lacks one or more tool scopes');
+      }
+      const result = await options.rpcHandler(payload, { principal, requestId, transport: 'streamable-http', resolveVaultContext });
+      if (result === undefined) {
+        response.statusCode = 202;
+        response.end();
+        return;
+      }
+      if (!accepts(request, JSON_CONTENT_TYPE) && accepts(request, SSE_CONTENT_TYPE)) writeSse(response, result);
+      else writeJson(response, 200, result);
+    } catch (error) {
+      if (response.writableEnded) return;
+      const status = error instanceof HttpMcpError ? error.status : 500;
+      const code = error instanceof HttpMcpError ? error.code : 'internal_error';
+      const message = error instanceof HttpMcpError ? error.message : 'internal server error';
+      writeJson(response, status, { error: { code, message }, requestId });
+    }
+  };
+}
+
+export async function startStreamableHttpMcpServer(options = {}) {
+  const host = String(options.host || '127.0.0.1');
+  const port = integer(options.port, 'port', 0, 65_535, 0);
+  if (!['127.0.0.1', '::1', 'localhost'].includes(host) && options.allowPublicListener !== true) {
+    throw new Error('public MCP listeners require allowPublicListener=true and an external TLS terminator');
+  }
+  const handler = createStreamableHttpMcpHandler(options);
+  const server = createServer((request, response) => {
+    handler(request, response).catch(() => {
+      if (!response.writableEnded) writeJson(response, 500, { error: { code: 'internal_error', message: 'internal server error' } });
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+  const address = server.address();
+  return Object.freeze({
+    server,
+    address,
+    close: () => new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())),
+  });
+}

package/packages/mcp-server/src/remote-policy.js

@@ -0,0 +1,72 @@
+const VAULT_CUSTODY_FIELDS = Object.freeze(['bundlePath', 'bundle_path', 'insecureDevMode', 'insecure_dev_mode']);
+const VAULT_READ_POLICY_FIELDS = Object.freeze([...VAULT_CUSTODY_FIELDS, 'allowOldEpochReads', 'allow_old_epoch_reads']);
+const VAULT_IDENTITY_FIELDS = Object.freeze([...VAULT_CUSTODY_FIELDS, 'tenant_id', 'subject_id', 'actor_id', 'policy_id']);
+
+function policy(scopes = [], options = {}) {
+  return Object.freeze({
+    requiredScopes: Object.freeze(['mcp:invoke', ...scopes]),
+    vaultBinding: options.vaultBinding || 'none',
+    tenantBinding: options.tenantBinding || 'none',
+    clientForbiddenFields: Object.freeze([...(options.clientForbiddenFields || [])]),
+  });
+}
+
+export const MCP_REMOTE_TOOL_POLICY = Object.freeze({
+  enigma_private_handoff_health: policy(),
+  enigma_routing_contract: policy(),
+  enigma_start_private_session: policy(),
+  enigma_complete: policy(['models:invoke']),
+  enigma_generate_image: policy(['images:generate']),
+  enigma_init: policy(['memory:write'], { vaultBinding: 'write', tenantBinding: 'inject', clientForbiddenFields: VAULT_IDENTITY_FIELDS }),
+  enigma_remember: policy(['memory:write'], { vaultBinding: 'write', clientForbiddenFields: VAULT_CUSTODY_FIELDS }),
+  enigma_search: policy(['memory:read'], { vaultBinding: 'read', clientForbiddenFields: VAULT_READ_POLICY_FIELDS }),
+  enigma_context_pack: policy(['memory:read'], { vaultBinding: 'read', clientForbiddenFields: VAULT_READ_POLICY_FIELDS }),
+  enigma_delete: policy(['memory:delete'], { vaultBinding: 'write', clientForbiddenFields: VAULT_CUSTODY_FIELDS }),
+  enigma_x402_execute: policy(['payments:execute']),
+  enigma_vault_rotate: policy(['vault:admin'], { vaultBinding: 'admin', clientForbiddenFields: VAULT_CUSTODY_FIELDS }),
+  enigma_vault_seal: policy(['vault:admin'], { vaultBinding: 'admin', clientForbiddenFields: VAULT_CUSTODY_FIELDS }),
+  enigma_vault_reset: policy(['vault:admin'], { vaultBinding: 'admin', clientForbiddenFields: VAULT_CUSTODY_FIELDS }),
+  enigma_verify_receipts: policy(['memory:read'], { vaultBinding: 'read', clientForbiddenFields: ['bundlePath', 'bundle_path'] }),
+  enigma_swarm_register_agent: policy(['swarm:write'], { vaultBinding: 'write', clientForbiddenFields: ['bundlePath', 'bundle_path'] }),
+  enigma_graph_query: policy(['swarm:read'], { vaultBinding: 'read', clientForbiddenFields: ['bundlePath', 'bundle_path'] }),
+  enigma_cluster_memories: policy(['swarm:read'], { vaultBinding: 'read', clientForbiddenFields: ['bundlePath', 'bundle_path'] }),
+  enigma_swarm_sync: policy(['swarm:write'], { vaultBinding: 'write', clientForbiddenFields: ['bundlePath', 'bundle_path'] }),
+  enigma_immune_ingress: policy(['security:inspect']),
+  enigma_meter_usage: policy(['metering:write'], { tenantBinding: 'inject', clientForbiddenFields: ['tenant_id', 'tenantId'] }),
+  enigma_settlement_job: policy(['settlement:write'], { tenantBinding: 'inject', clientForbiddenFields: ['tenant_id', 'tenantId'] }),
+  enigma_settlement_capacity: policy(['settlement:operator']),
+  enigma_settlement_quote: policy(['settlement:write'], { tenantBinding: 'validate_nested' }),
+  enigma_settlement_receipt: policy(['settlement:write'], { tenantBinding: 'validate_nested' }),
+  enigma_settlement_verify: policy(['settlement:read'], { tenantBinding: 'validate_nested' }),
+  enigma_settlement_batch: policy(['settlement:write'], { tenantBinding: 'validate_nested' }),
+  enigma_nullifier_record_tombstone: policy(['nullifier:prepare']),
+});
+
+export function remoteToolPolicy(name) {
+  return Object.prototype.hasOwnProperty.call(MCP_REMOTE_TOOL_POLICY, name) ? MCP_REMOTE_TOOL_POLICY[name] : null;
+}
+
+export function assertRemoteToolPolicyCoverage(descriptors) {
+  if (!Array.isArray(descriptors)) throw new TypeError('tool descriptors must be an array');
+  const descriptorNames = new Set(descriptors.map((descriptor) => descriptor?.name));
+  const policyNames = new Set(Object.keys(MCP_REMOTE_TOOL_POLICY));
+  const missing = [...descriptorNames].filter((name) => !policyNames.has(name));
+  const stale = [...policyNames].filter((name) => !descriptorNames.has(name));
+  if (missing.length || stale.length || descriptorNames.has(undefined)) {
+    throw new Error(`remote MCP policy coverage mismatch; missing=${missing.join(',') || 'none'} stale=${stale.join(',') || 'none'}`);
+  }
+  return true;
+}
+
+export function requiredScopesForMcpPayload(payload) {
+  const required = new Set(['mcp:invoke']);
+  const requests = Array.isArray(payload) ? payload : [payload];
+  for (const request of requests) {
+    if (request?.method !== 'tools/call') continue;
+    const name = request?.params?.name;
+    const toolPolicy = remoteToolPolicy(name);
+    if (!toolPolicy) continue;
+    for (const scope of toolPolicy.requiredScopes) required.add(scope);
+  }
+  return [...required];
+}