@dzhechkov/cloudru-hub 0.1.12 → 0.1.14

package/src/k8s-approval.js

@@ -0,0 +1,208 @@
+'use strict';
+
+// An opt-in, exact-manifest approval for an existing Kubernetes cluster.
+// The model never supplies the manifest, cluster, namespace or confirmation
+// forwarded to the engine. The local operator reviews the file and its digest.
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { isDeepStrictEqual } = require('util');
+const YAML = require('yaml');
+const { readCredentials, UUID } = require('./credentials');
+const { approvalRoot } = require('./deploy-approval');
+
+const APPROVAL_ID = /^k8s-[0-9a-f]{12}$/;
+const DNS_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+const MAX_MANIFEST = 64 * 1024;
+const PILOT_IMAGE = 'docker.io/library/busybox@sha256:66a6306db78bf2dbf3487f293aa8d6990d8e506fdffab9cc43fe422becf886e4';
+const isRecord = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const sha256 = (raw) => crypto.createHash('sha256').update(raw).digest('hex');
+function keys(value, allowed, label) {
+  if (!isRecord(value) || Object.keys(value).some((key) => !allowed.includes(key))) {
+    throw new Error(`${label} contains unsupported fields`);
+  }
+}
+function exact(value, expected, label) {
+  if (!isDeepStrictEqual(value, expected)) throw new Error(`${label} differs from the bounded Snake profile`);
+}
+function quantity(value, max, suffix = '') {
+  if (typeof value !== 'string' || !new RegExp(`^[1-9][0-9]{0,4}${suffix}$`).test(value)) return false;
+  return Number.parseInt(value, 10) <= max;
+}
+
+function privateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const st = fs.lstatSync(dir);
+  if (!st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 ||
+      (typeof process.getuid === 'function' && st.uid !== process.getuid())) {
+    throw new Error('approval directory must be private and owned');
+  }
+}
+
+function privateJson(file) {
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 || st.size > MAX_MANIFEST + 8192 ||
+      (typeof process.getuid === 'function' && st.uid !== process.getuid())) {
+    throw new Error('approval file must be private, owned and bounded');
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function validateManifest(raw, namespace) {
+  if (typeof raw !== 'string' || Buffer.byteLength(raw) < 1 || Buffer.byteLength(raw) > MAX_MANIFEST) {
+    throw new Error('manifest must be non-empty and at most 64 KiB');
+  }
+  if (typeof namespace !== 'string' || !DNS_NAME.test(namespace) || namespace.length > 63) throw new Error('invalid namespace');
+  const docs = YAML.parseAllDocuments(raw, { uniqueKeys: true, maxAliasCount: 0 });
+  if (docs.length !== 3 || docs.some((d) => d.errors.length)) throw new Error('manifest must contain exactly three valid YAML documents');
+  const resources = docs.map((d) => d.toJS({ maxAliasCount: 0 }));
+  const byKind = new Map();
+  for (const r of resources) {
+    if (!isRecord(r) || !isRecord(r.metadata) || typeof r.metadata.name !== 'string' || !DNS_NAME.test(r.metadata.name) ||
+        r.metadata.namespace !== namespace || !['ConfigMap', 'Deployment', 'Service'].includes(r.kind) || byKind.has(r.kind)) {
+      throw new Error('manifest requires one namespaced ConfigMap, Deployment and Service with valid unique names');
+    }
+    if (r.apiVersion !== (r.kind === 'Deployment' ? 'apps/v1' : 'v1')) throw new Error('unexpected Kubernetes apiVersion');
+    keys(r.metadata, ['name', 'namespace'], 'metadata');
+    byKind.set(r.kind, r);
+  }
+  if (byKind.size !== 3) throw new Error('manifest requires ConfigMap, Deployment and Service');
+  const config = byKind.get('ConfigMap');
+  const deploy = byKind.get('Deployment');
+  const service = byKind.get('Service');
+  const app = deploy.metadata.name;
+  keys(config, ['apiVersion', 'kind', 'metadata', 'data'], 'ConfigMap');
+  keys(deploy, ['apiVersion', 'kind', 'metadata', 'spec'], 'Deployment');
+  keys(service, ['apiVersion', 'kind', 'metadata', 'spec'], 'Service');
+  if (config.metadata.name !== `${app}-html` || service.metadata.name !== app ||
+      !isRecord(config.data) || typeof config.data['index.html'] !== 'string' ||
+      Buffer.byteLength(config.data['index.html']) < 1 || Buffer.byteLength(config.data['index.html']) > 20 * 1024 ||
+      Object.keys(config.data).length !== 1 || config.binaryData !== undefined) {
+    throw new Error('ConfigMap must contain only bounded index.html for this app');
+  }
+  const spec = deploy.spec;
+  const pod = spec?.template?.spec;
+  const container = Array.isArray(pod?.containers) && pod.containers.length === 1 ? pod.containers[0] : null;
+  const image = container?.image;
+  keys(spec, ['replicas', 'selector', 'template'], 'Deployment spec');
+  keys(spec.selector, ['matchLabels'], 'Deployment selector');
+  keys(spec.template, ['metadata', 'spec'], 'pod template');
+  keys(spec.template.metadata, ['labels'], 'pod metadata');
+  keys(pod, ['automountServiceAccountToken', 'securityContext', 'containers', 'volumes'], 'pod spec');
+  if (container) keys(container, ['name', 'image', 'command', 'args', 'ports', 'readinessProbe', 'resources', 'securityContext', 'volumeMounts'], 'container');
+  keys(service.spec, ['type', 'selector', 'ports'], 'Service spec');
+  exact(spec.selector.matchLabels, { app }, 'Deployment selector');
+  exact(spec.template.metadata.labels, { app }, 'pod labels');
+  exact(service.spec.selector, { app }, 'Service selector');
+  exact(pod.securityContext, { runAsNonRoot: true }, 'pod securityContext');
+  if (container) {
+    exact(container.ports, [{ containerPort: 8080 }], 'container ports');
+    exact(container.securityContext, { allowPrivilegeEscalation: false, readOnlyRootFilesystem: true,
+      runAsUser: 10001, runAsGroup: 10001, capabilities: { drop: ['ALL'] } }, 'container securityContext');
+    exact(container.command, ['httpd'], 'container command');
+    exact(container.args, ['-f', '-p', '8080', '-h', '/www'], 'container args');
+    exact(container.readinessProbe, { httpGet: { path: '/', port: 8080 } }, 'readiness probe');
+  }
+  if (spec?.replicas !== 1 || spec?.selector?.matchLabels?.app !== app ||
+      spec?.template?.metadata?.labels?.app !== app || !isRecord(pod) ||
+      pod.hostNetwork || pod.hostPID || pod.hostIPC || pod.serviceAccountName ||
+      pod.automountServiceAccountToken !== false || pod.initContainers !== undefined ||
+      !container || container.name !== app || image !== PILOT_IMAGE ||
+      container.securityContext?.privileged === true || container.securityContext?.allowPrivilegeEscalation !== false ||
+      pod.securityContext?.runAsNonRoot !== true ||
+      container.readinessProbe?.httpGet?.path !== '/' || container.readinessProbe?.httpGet?.port !== 8080 ||
+      !isRecord(container.resources?.requests) || !isRecord(container.resources?.limits) ||
+      !container.resources.requests.cpu || !container.resources.requests.memory ||
+      !quantity(container.resources.requests.cpu, 500, 'm') || !quantity(container.resources.limits.cpu, 1000, 'm') ||
+      !quantity(container.resources.requests.memory, 512, 'Mi') || !quantity(container.resources.limits.memory, 1024, 'Mi') ||
+      Object.keys(container.resources.requests).length !== 2 || Object.keys(container.resources.limits).length !== 2 ||
+      Number.parseInt(container.resources.requests.cpu, 10) > Number.parseInt(container.resources.limits.cpu, 10) ||
+      Number.parseInt(container.resources.requests.memory, 10) > Number.parseInt(container.resources.limits.memory, 10) ||
+      !Array.isArray(pod.volumes) || pod.volumes.length !== 1 || pod.volumes[0]?.configMap?.name !== config.metadata.name ||
+      !Array.isArray(container.volumeMounts) || container.volumeMounts.length !== 1 ||
+      container.volumeMounts[0]?.name !== pod.volumes[0]?.name || !container.volumeMounts[0]?.readOnly ||
+      container.volumeMounts[0]?.mountPath !== '/www') {
+    throw new Error('Deployment must be a bounded non-root single-replica pod with pinned image, probes and resources');
+  }
+  exact(pod.volumes[0], { name: 'html', configMap: { name: config.metadata.name } }, 'pod volume');
+  exact(container.volumeMounts[0], { name: 'html', mountPath: '/www', readOnly: true }, 'volume mount');
+  exact(service.spec.ports, [{ port: 80, targetPort: 8080 }], 'Service ports');
+  if (service.spec?.type !== 'ClusterIP' || service.spec?.selector?.app !== app ||
+      !Array.isArray(service.spec?.ports) || service.spec.ports.length !== 1 ||
+      service.spec.ports[0]?.port !== 80 || service.spec.ports[0]?.targetPort !== 8080 ||
+      service.spec.externalIPs !== undefined || service.spec.loadBalancerIP !== undefined ||
+      service.spec.loadBalancerClass !== undefined) {
+    throw new Error('Service must be ClusterIP port 80 to pod port 8080 without external IPs');
+  }
+  return { app, resources: resources.map((r) => ({ kind: r.kind, name: r.metadata.name })), image };
+}
+
+function approvalFile(id, env = process.env) {
+  if (!APPROVAL_ID.test(id)) throw new Error('invalid Kubernetes approval ID');
+  return path.join(approvalRoot(env), `${id}.json`);
+}
+
+function issueK8sApproval(clusterId, namespace, manifestFile, reviewedSha256, env = process.env, now = Date.now()) {
+  if (!UUID.test(clusterId || '')) throw new Error('cluster_id must be a UUID');
+  if (!DIGEST.test(reviewedSha256 || '')) throw new Error('reviewed manifest SHA-256 is required');
+  const st = fs.lstatSync(manifestFile);
+  if (!st.isFile() || st.isSymbolicLink() || st.size < 1 || st.size > MAX_MANIFEST) {
+    throw new Error('manifest source must be a bounded regular file');
+  }
+  const manifest = fs.readFileSync(manifestFile, 'utf8');
+  const details = validateManifest(manifest, namespace);
+  const digest = sha256(manifest);
+  if (digest !== reviewedSha256) throw new Error('manifest digest differs from reviewed SHA-256');
+  const credentials = readCredentials(env);
+  const root = approvalRoot(env);
+  privateDir(root);
+  const id = `k8s-${crypto.randomBytes(6).toString('hex')}`;
+  const record = { id, projectId: credentials.projectId, clusterId, namespace, manifest, digest,
+    app: details.app, issuedAt: now, expiresAt: now + 10 * 60_000 };
+  fs.writeFileSync(approvalFile(id, env), JSON.stringify(record) + '\n', { flag: 'wx', mode: 0o600 });
+  return { approvalId: id, projectId: record.projectId, clusterId, namespace, manifestSha256: digest,
+    resources: details.resources, image: details.image, expiresAt: record.expiresAt,
+    estimateScope: 'existing cluster only; no cluster, worker, NAT or public load balancer is created' };
+}
+
+function consumeK8sApproval(id, env = process.env, now = Date.now()) {
+  const file = approvalFile(id, env);
+  const a = privateJson(file);
+  const credentials = readCredentials(env);
+  if (a.id !== id || a.projectId !== credentials.projectId || !UUID.test(a.clusterId || '') ||
+      !Number.isFinite(a.expiresAt) || a.expiresAt <= now || !DIGEST.test(a.digest || '') ||
+      sha256(a.manifest) !== a.digest || validateManifest(a.manifest, a.namespace).app !== a.app) {
+    throw new Error('Kubernetes approval does not match manifest, project or time');
+  }
+  const spent = path.join(approvalRoot(env), `${id}.used-${crypto.randomBytes(8).toString('hex')}.json`);
+  fs.renameSync(file, spent);
+  const session = { id, projectId: a.projectId, clusterId: a.clusterId, namespace: a.namespace,
+    app: a.app, expiresAt: now + 2 * 60 * 60_000 };
+  fs.writeFileSync(path.join(approvalRoot(env), `${id}.session.json`), JSON.stringify(session) + '\n', { flag: 'wx', mode: 0o600 });
+  return { clusterId: a.clusterId, namespace: a.namespace, manifest: a.manifest, app: a.app };
+}
+
+function k8sSession(id, env = process.env, now = Date.now()) {
+  if (!APPROVAL_ID.test(id)) throw new Error('invalid Kubernetes approval ID');
+  const s = privateJson(path.join(approvalRoot(env), `${id}.session.json`));
+  if (s.id !== id || s.projectId !== readCredentials(env).projectId || !UUID.test(s.clusterId || '') ||
+      typeof s.namespace !== 'string' || !DNS_NAME.test(s.namespace) ||
+      typeof s.app !== 'string' || !DNS_NAME.test(s.app) || !Number.isFinite(s.expiresAt) || s.expiresAt <= now) {
+    throw new Error('Kubernetes verification session is expired or mismatched');
+  }
+  return s;
+}
+
+function verificationArgs(session, query) {
+  const prefix = `-n ${session.namespace}`;
+  switch (query) {
+    case 'pods': return `${prefix} get pods -l app=${session.app} -o json`;
+    case 'deployment': return `${prefix} get deployment ${session.app} -o json`;
+    case 'service': return `${prefix} get service ${session.app} -o json`;
+    case 'rollout': return `${prefix} rollout status deployment/${session.app} --timeout=90s`;
+    default: throw new Error('query must be pods, deployment, service or rollout');
+  }
+}
+
+module.exports = { PILOT_IMAGE, validateManifest, issueK8sApproval, consumeK8sApproval, k8sSession, verificationArgs };

package/src/probe-child.js

@@ -0,0 +1,38 @@
+'use strict';
+// One-shot live tools/list probe. MCP servers may stay alive after stdin EOF;
+// terminate the child after the first matching response instead of waiting for exit.
+const { spawn } = require('child_process');
+
+const bin = process.argv[2];
+const child = spawn(bin, ['mcp'], { stdio: ['pipe', 'pipe', 'ignore'] });
+let buffer = '';
+let done = false;
+const fail = (message) => {
+  if (done) return;
+  done = true;
+  process.stderr.write(message + '\n');
+  child.kill();
+  process.exitCode = 1;
+};
+child.on('error', (error) => fail(error.message));
+child.on('exit', (code) => { if (!done) fail(`engine exited before tools/list: ${code}`); });
+child.stdout.setEncoding('utf8');
+child.stdout.on('data', (chunk) => {
+  if (done) return;
+  buffer += chunk;
+  if (Buffer.byteLength(buffer) > 16 * 1024 * 1024) { fail('tools/list response too large'); return; }
+  let end;
+  while ((end = buffer.indexOf('\n')) >= 0) {
+    const line = buffer.slice(0, end).trim();
+    buffer = buffer.slice(end + 1);
+    if (!line) continue;
+    let message;
+    try { message = JSON.parse(line); } catch { fail('engine emitted invalid JSON'); return; }
+    if (message.id !== 1) continue;
+    done = true;
+    process.stdout.write(JSON.stringify(message) + '\n');
+    child.kill();
+    return;
+  }
+});
+child.stdin.end(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }) + '\n');

package/src/resolve.js

@@ -4,7 +4,7 @@
 //   1. env CLOUDRU_VM_BIN                          — explicit path (local baseline testing)
 //   2. config enginePath                           — ~/.cloudru-hub/config.json (or $CLOUDRU_HUB_CONFIG)
 //   3. platform package @dzhechkov/cloudru-vm-<os>-<cpu>/native/cloudru-vm
-//      (does not exist until the ADR-001 licence grant clears — see LICENSE Part 2)
+//      (installed automatically when its optional dependency is published)
 //   4. loud, esbuild-style error explaining all three paths and the licence hold.
 //
 // sha256 policy: the resolved binary is hashed and compared against the pinned map in
@@ -64,7 +64,7 @@ function resolveEngine(env = process.env) {
       const pkgJson = require.resolve(`${platformPkg}/package.json`);
       candidates.push({ path: path.join(path.dirname(pkgJson), 'native', 'cloudru-vm'), source: 'platform-package' });
     } catch {
-      /* optional platform package not installed — expected while the ADR-001 hold is in force */
+      /* optional platform package unavailable on this host or omitted by the installer */
     }
   }
 
@@ -94,7 +94,7 @@ function resolveEngine(env = process.env) {
       `  2. enginePath in ${configPath(env)}          ${cfg.enginePath ? `(set, but not a file: ${cfg.enginePath})` : '(unset/absent)'}\n` +
       `  3. optional dependency ${(PKG.cloudruHub && PKG.cloudruHub.platformPackages && PKG.cloudruHub.platformPackages[key]) || '<none for ' + key + '>'} (not installed)\n` +
       'Local testing: point $CLOUDRU_VM_BIN at an engine build (see docs/LOCAL-TESTING.md).\n' +
-      'The hosted platform package does not exist yet: its first publication still requires the ADR-002 trusted-CI binary build (see LICENSE Part 2 and THIRD_PARTY_NOTICES).',
+      'If the platform package has been released, install optional dependencies; otherwise provide a pinned local engine build.',
   };
 }
 

package/src/safe-mcp.js

@@ -0,0 +1,268 @@
+'use strict';
+
+// Read-only MCP boundary for hosts whose hook/permission paths have not been
+// live-probed. The host never gets a raw engine channel through this command.
+const { spawn } = require('child_process');
+const { loadClassification } = require('./classification');
+const { resolveEngine } = require('./resolve');
+const { selectedToolNames } = require('./toolsets');
+const { readCredentials, readOptionalCredentials } = require('./credentials');
+const { consumeApproval, recordDeployedVM, approvedVM } = require('./deploy-approval');
+const { consumeK8sApproval, k8sSession, verificationArgs } = require('./k8s-approval');
+
+const MAX_LINE = 1024 * 1024;
+const idKey = (id) => JSON.stringify(id);
+const errorResponse = (id, message, code = -32000) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+function redactDeploySecrets(value) {
+  if (Array.isArray(value)) return value.map(redactDeploySecrets);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !/password|secret|private.?key|access.?token/i.test(key))
+    .map(([key, item]) => [key, redactDeploySecrets(item)]));
+}
+
+function lineReader(stream, onLine, onError) {
+  let buffer = '';
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk) => {
+    buffer += chunk;
+    if (Buffer.byteLength(buffer) > MAX_LINE * 2) return onError('MCP input exceeded line limit');
+    for (;;) {
+      const end = buffer.indexOf('\n');
+      if (end < 0) break;
+      const line = buffer.slice(0, end).trim();
+      buffer = buffer.slice(end + 1);
+      if (Buffer.byteLength(line) > MAX_LINE) return onError('MCP line exceeded limit');
+      if (line) onLine(line);
+    }
+    if (Buffer.byteLength(buffer) > MAX_LINE) onError('MCP line exceeded limit');
+  });
+  stream.on('end', () => { if (buffer.trim()) onError('incomplete MCP line'); });
+}
+
+function runSafeMcp(options = {}) {
+  const resolved = options.resolved || resolveEngine();
+  const cls = options.classification || loadClassification();
+  const stderr = options.stderr || process.stderr;
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+  let selected;
+  const deployProfile = options.toolsets === 'vm-deploy';
+  const k8sProfile = options.toolsets === 'k8s-deploy';
+  let credentials;
+  try {
+    selected = new Set(selectedToolNames(options.toolsets || 'all', cls));
+    if (deployProfile || k8sProfile) credentials = readCredentials(options.env || process.env);
+    else if ([...selected].some((name) => name.startsWith('billing_'))) {
+      credentials = readOptionalCredentials(options.env || process.env);
+    }
+  }
+  catch (error) { stderr.write(`cloudru-hub mcp-safe: ${error.message}\n`); return 1; }
+  if (resolved.error || !resolved.verified || resolved.sha256 !== cls.engineSha256) {
+    stderr.write('cloudru-hub mcp-safe: pinned engine SHA-256 required; refusing to start\n');
+    return 1;
+  }
+
+  const engine = spawn(resolved.path, ['mcp'], {
+    stdio: ['pipe', 'pipe', 'inherit'],
+    env: credentials ? { ...(options.env || process.env), ...credentials.env } : (options.env || process.env),
+  });
+  const pending = new Map();
+  // The pinned engine's tool inventory is fixed for this process. Keep a
+  // filtered copy so a host keepalive can be answered while Go is handling a
+  // long deploy_apply request on its serial stdio loop.
+  let cachedToolsList = null;
+  let stopped = false;
+  let inputEnded = false;
+  let closing = false;
+  const emit = (obj) => stdout.write(JSON.stringify(obj) + '\n');
+  const stop = (reason) => {
+    if (stopped) return;
+    stopped = true;
+    stderr.write(`cloudru-hub mcp-safe: ${reason}\n`);
+    for (const key of pending.keys()) {
+      emit(errorResponse(JSON.parse(key), 'Cloud.ru engine connection closed'));
+    }
+    pending.clear();
+    stdin.destroy();
+    engine.stdin.end();
+    if (!engine.killed) engine.kill();
+    process.exitCode = 1;
+  };
+  engine.on('error', (error) => stop(`engine failed: ${error.message}`));
+  engine.on('exit', (code) => {
+    if (!stopped && !closing) stop(`engine exited with status ${code === null ? 'unknown' : code}`);
+  });
+  engine.stdin.on('error', (error) => stop(`engine input failed: ${error.message}`));
+  const closeIfDone = () => {
+    if (inputEnded && pending.size === 0 && !closing) {
+      closing = true;
+      engine.stdin.end();
+    }
+  };
+  stdin.on('end', () => { inputEnded = true; closeIfDone(); });
+
+  lineReader(stdin, (line) => {
+    if (stopped) return;
+    let message;
+    try { message = JSON.parse(line); } catch { emit(errorResponse(null, 'invalid JSON', -32700)); return; }
+    if (!message || Array.isArray(message) || typeof message !== 'object' || message.jsonrpc !== '2.0') {
+      emit(errorResponse(null, 'invalid JSON-RPC request', -32600)); return;
+    }
+    const hasId = Object.hasOwn(message, 'id');
+    const method = message.method;
+    if (!hasId) {
+      if (method === 'notifications/initialized') {
+        engine.stdin.write(JSON.stringify({ jsonrpc: '2.0', method }) + '\n');
+      }
+      return;
+    }
+    if (typeof method !== 'string' || (typeof message.id !== 'string' && !Number.isSafeInteger(message.id))) {
+      emit(errorResponse(message.id ?? null, 'invalid JSON-RPC request', -32600)); return;
+    }
+    const key = idKey(message.id);
+    if (pending.has(key)) { emit(errorResponse(message.id, 'duplicate request id', -32600)); return; }
+    if (method === 'tools/list' && cachedToolsList &&
+        (!Object.hasOwn(message, 'params') ||
+         (message.params && !Array.isArray(message.params) && typeof message.params === 'object' && Object.keys(message.params).length === 0))) {
+      emit({ jsonrpc: '2.0', id: message.id, result: cachedToolsList });
+      return;
+    }
+    let params;
+    let approval;
+    if (method === 'tools/call') {
+      const input = message.params;
+      const name = input && !Array.isArray(input) && typeof input === 'object' ? input.name : undefined;
+      if (typeof name !== 'string' || !selected.has(name)) {
+        emit(errorResponse(message.id, `tool ${typeof name === 'string' ? name : '<missing>'} is unavailable in this profile`));
+        return;
+      }
+      const args = input.arguments === undefined ? {} : input.arguments;
+      if (!args || typeof args !== 'object' || Array.isArray(args)) {
+        emit(errorResponse(message.id, 'tool arguments must be an object', -32602)); return;
+      }
+      // Go's encoding/json accepts case-insensitive struct field aliases. Never forward
+      // the original envelope: {name:"vm_list",Name:"deploy"} can otherwise execute deploy.
+      if (deployProfile && name === 'deploy_apply') {
+        try {
+          if (typeof args.plan_id !== 'string') throw new Error('plan_id is required');
+          approval = consumeApproval(args.plan_id, options.env || process.env);
+          params = { name, arguments: { plan_id: args.plan_id, confirmed: true } };
+        } catch (error) { emit(errorResponse(message.id, `deployment approval rejected: ${error.message}`)); return; }
+      } else if (deployProfile && name === 'vm_exec') {
+        try {
+          if (typeof args.command !== 'string' || !args.command.trim() || args.command.length > 65536) {
+            throw new Error('command must be a non-empty string of at most 65536 characters');
+          }
+          const vm = approvedVM(args.vm || args.vm_id, options.env || process.env);
+          params = { name, arguments: { vm: vm.vmId, user: vm.sshUser, command: args.command } };
+        } catch (error) { emit(errorResponse(message.id, `vm_exec rejected: ${error.message}`)); return; }
+      } else if (k8sProfile && name === 'k8s_apply') {
+        try {
+          if (Object.keys(args).length !== 1 || typeof args.approval_id !== 'string') throw new Error('only approval_id is accepted');
+          const approved = consumeK8sApproval(args.approval_id, options.env || process.env);
+          params = { name, arguments: { cluster_id: approved.clusterId, namespace: approved.namespace,
+            manifest: approved.manifest, create_only: true, confirmed: true } };
+        } catch (error) { emit(errorResponse(message.id, `Kubernetes approval rejected: ${error.message}`)); return; }
+      } else if (k8sProfile && name === 'k8s_kubectl') {
+        try {
+          if (Object.keys(args).length !== 2 || typeof args.approval_id !== 'string' || typeof args.query !== 'string') {
+            throw new Error('only approval_id and query are accepted');
+          }
+          const session = k8sSession(args.approval_id, options.env || process.env);
+          params = { name, arguments: { cluster_id: session.clusterId, args: verificationArgs(session, args.query) } };
+        } catch (error) { emit(errorResponse(message.id, `Kubernetes verification rejected: ${error.message}`)); return; }
+      } else {
+        params = { name, arguments: args };
+      }
+    } else if (!['initialize', 'ping', 'tools/list'].includes(method)) {
+      emit(errorResponse(message.id, `method ${method} is unavailable in read-only mode`, -32601));
+      return;
+    } else if (method === 'initialize') {
+      // The pinned engine requires the client's protocol version and capabilities.
+      const p = message.params;
+      if (!p || typeof p !== 'object' || Array.isArray(p)) {
+        emit(errorResponse(message.id, 'initialize params must be an object', -32602)); return;
+      }
+      params = { protocolVersion: p.protocolVersion, capabilities: p.capabilities, clientInfo: p.clientInfo };
+    }
+    pending.set(key, { method, approval });
+    engine.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, method, ...(params ? { params } : {}) }) + '\n');
+  }, stop);
+
+  lineReader(engine.stdout, (line) => {
+    if (stopped) return;
+    let message;
+    try { message = JSON.parse(line); } catch { stop('engine emitted invalid JSON'); return; }
+    if (!message || typeof message !== 'object' || !Object.hasOwn(message, 'id')) {
+      // MCP progress/log notifications are not needed for the safe read-only surface.
+      return;
+    }
+    const key = idKey(message.id);
+    const request = pending.get(key);
+    if (!request) { stop('engine emitted an unsolicited response'); return; }
+    const { method, approval } = request;
+    pending.delete(key);
+    if (method === 'tools/list' && !message.error) {
+      if (!message.result || !Array.isArray(message.result.tools)) { stop('engine tools/list response malformed'); return; }
+      message.result = { ...message.result, tools: message.result.tools.filter((tool) =>
+        tool && typeof tool.name === 'string' && selected.has(tool.name)).map((tool) => {
+        if (!k8sProfile) return tool;
+        if (tool.name === 'k8s_apply') return { ...tool,
+          description: 'Apply one locally reviewed Snake manifest to one existing cluster. Pass only the local approval ID.',
+          inputSchema: { type: 'object', properties: { approval_id: { type: 'string' } }, required: ['approval_id'], additionalProperties: false } };
+        if (tool.name === 'k8s_kubectl') return { ...tool,
+          description: 'Read only pods, deployment, service or rollout status for the previously approved Snake workload.',
+          inputSchema: { type: 'object', properties: { approval_id: { type: 'string' },
+            query: { type: 'string', enum: ['pods', 'deployment', 'service', 'rollout'] } },
+          required: ['approval_id', 'query'], additionalProperties: false } };
+        return tool;
+      }) };
+      // A paginated list could conceal tools from filtering/coverage checks.
+      if (message.result.nextCursor) { stop('engine tools/list pagination is unsupported'); return; }
+      cachedToolsList = message.result;
+    }
+    if (method === 'initialize' && message.result && message.result.capabilities) {
+      message.result = { ...message.result, capabilities: { tools: message.result.capabilities.tools || {} } };
+    }
+    if (approval && !message.error) {
+      // The engine returns an MCP text result containing its JSON deploy result.
+      // Keep the model from seeing a generated login password: vm_exec uses the
+      // engine-managed SSH key. Ambiguous responses require inspection.
+      const item = message.result?.content?.find((x) => x.type === 'text');
+      let deploy;
+      try { deploy = JSON.parse(item?.text || ''); }
+      catch {
+        message.result = { isError: true, content: [{ type: 'text', text: 'deploy_apply returned an unreadable outcome; inspect the live VM inventory before retrying' }] };
+        emit(message); closeIfDone(); return;
+      }
+      if (!deploy || typeof deploy !== 'object' || Array.isArray(deploy)) {
+        message.result = { isError: true, content: [{ type: 'text', text: 'deploy_apply returned an invalid outcome; inspect the live VM inventory before retrying' }] };
+        emit(message); closeIfDone(); return;
+      }
+      const safe = redactDeploySecrets(deploy);
+      if (!message.result?.isError && approval.siteMode && deploy.status === 'running' && deploy.http_verification?.verified === true) {
+        // Static-site delivery is verified over HTTP. It does not imply SSH is
+        // available, so never create a vm_exec session for this VM.
+      } else if (!message.result?.isError && !approval.siteMode && deploy.status === 'running') {
+        try {
+          const session = recordDeployedVM(approval, deploy, options.env || process.env);
+          safe.approved_vm_session_expires_at = new Date(session.expiresAt).toISOString();
+        } catch (error) {
+          message.result.isError = true;
+          safe.recovery = `VM may exist but the approved execution session was not recorded: ${error.message}. Inspect VM inventory before retrying.`;
+        }
+      } else {
+        message.result.isError = true;
+        safe.recovery = 'A VM may exist. Inspect the returned VM UUID and live inventory before retrying; a fresh plan and approval may be needed.';
+      }
+      item.text = JSON.stringify(safe);
+    }
+    emit(message);
+    closeIfDone();
+  }, stop);
+  return null;
+}
+
+module.exports = { runSafeMcp, MAX_LINE };

package/src/toolsets.js

@@ -0,0 +1,58 @@
+'use strict';
+// Named, auditable discovery groups. Each member must remain classified allow.
+const { loadClassification } = require('./classification');
+
+const GROUPS = Object.freeze({
+  inventory: ['status', 'list', 'vm_list', 'vm_get', 'list_zones', 'list_images', 'list_flavors', 'list_disk_types', 'list_subnets', 'org_projects', 'org_quotas'],
+  compute: ['vm_list', 'vm_get', 'disk_list', 'list_flavors', 'list_disk_types', 'list_zones', 'list_images', 'list_subnets', 'list_security_groups', 'list_floating_ips'],
+  kubernetes: ['k8s_list', 'k8s_get', 'k8s_options', 'k8s_plan', 'k8s_nodepools'],
+  data: ['pg_list', 'pg_get', 'pg_versions', 'pg_specs', 'pg_databases', 'pg_users', 'pg_backups', 'kafka_list', 'kafka_get', 'kafka_versions', 'kafka_specs', 'redis_list', 'redis_get', 'redis_versions', 'redis_specs'],
+  network: ['vpc_list', 'vpc_get', 'vpc_routes', 'snat_list', 'lb_list', 'lb_get', 'tg_list', 'tg_get', 'dns_zones', 'dns_zone_get', 'dns_records', 'dns_record_get'],
+  storage: ['disk_list', 's3_buckets', 's3_ls', 's3_get'],
+  billing: ['billing_balance', 'billing_consumption', 'billing_finops'],
+});
+
+// A separate, opt-in workflow. Mutators pass the proxy's local plan/VM guard;
+// combining this with a read-only group would blur that boundary.
+const VM_DEPLOY = Object.freeze([
+  'deploy_plan', 'deploy_apply', 'vm_exec', 'vm_list', 'vm_get',
+  'list_zones', 'list_images', 'list_flavors', 'list_disk_types',
+  'list_subnets', 'list_security_groups', 'status',
+]);
+const K8S_DEPLOY = Object.freeze([
+  'k8s_list', 'k8s_get', 'k8s_options', 'k8s_nodepools', 'k8s_apply', 'k8s_kubectl',
+]);
+
+function selectedToolNames(spec = 'all', cls = loadClassification()) {
+  if (spec === 'vm-deploy') {
+    for (const name of VM_DEPLOY) {
+      const permission = cls.tools[name]?.permission;
+      if (permission !== (['deploy_apply', 'vm_exec'].includes(name) ? 'ask' : 'allow')) {
+        throw new Error(`vm-deploy tool classification changed: ${name}`);
+      }
+    }
+    return [...VM_DEPLOY].sort();
+  }
+  if (spec === 'k8s-deploy') {
+    for (const name of K8S_DEPLOY) {
+      const permission = cls.tools[name]?.permission;
+      if (permission !== (['k8s_apply', 'k8s_kubectl'].includes(name) ? 'ask' : 'allow')) {
+        throw new Error(`k8s-deploy tool classification changed: ${name}`);
+      }
+    }
+    return [...K8S_DEPLOY].sort();
+  }
+  const names = Object.entries(cls.tools).filter(([, v]) => v.permission === 'allow').map(([name]) => name);
+  if (spec === 'all') return names.sort();
+  const parts = String(spec).split(',').map((x) => x.trim()).filter(Boolean);
+  if (parts.length === 0 || parts.includes('all') || parts.some((p) => !Object.hasOwn(GROUPS, p))) {
+    throw new Error(`invalid toolsets "${spec}"; choose all, vm-deploy, k8s-deploy, or comma-separated ${Object.keys(GROUPS).join(', ')}`);
+  }
+  const selected = [...new Set(parts.flatMap((p) => GROUPS[p]))].sort();
+  for (const name of selected) {
+    if (!cls.tools[name] || cls.tools[name].permission !== 'allow') throw new Error(`toolset contains non-allow tool: ${name}`);
+  }
+  return selected;
+}
+
+module.exports = { GROUPS, VM_DEPLOY, K8S_DEPLOY, selectedToolNames };