@dzhechkov/cloudru-hub 0.1.11 → 0.1.13

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dzhechkov/cloudru-hub",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "licenseHold": {
     "adr": "features/hermes-claude-adaptation/03_adr/001-licence-and-provenance-precondition.md",
     "note": "SATISFIED hold (ADR-001 AM-2, grant recorded 2026-08-12 — see grant-record-2026-08-12.md). The field deliberately STAYS: the dz guard `licence-hold` rule passes a satisfied hold with the trigger in place and keeps verifying LICENSE (no PENDING placeholder, Grant-Confirmation URL), THIRD_PARTY_NOTICES and the SPDX license field on every publish. test/pack-holds.test.mjs goes RED if this field is dropped or the LICENSE grant record is degraded."
   },
-  "description": "Unofficial Cloud.ru Evolution launcher for Claude Code and harness-cli targets: thin JS launcher for the cloudru-vm MCP engine (144 tools), per-target installers with a deterministic paid-step brake (permission ask/deny + PreToolUse veto hooks), and skill dialect compiler. The engine binary is resolved at RUNTIME, never bundled. NOT affiliated with Cloud.ru.",
+  "description": "Unofficial Cloud.ru Evolution launcher with a pinned cloud-write-blocking MCP proxy for Codex, Hermes, OpenCode and Pi, Claude Code permissions, and skill dialect compiler. Engine binary resolved at runtime, never bundled. NOT affiliated with Cloud.ru.",
   "main": "src/cli.js",
   "bin": {
     "cloudru-hub": "./bin/cloudru-hub.js"
@@ -26,9 +26,9 @@
   ],
   "cloudruHub": {
     "binaryHashes": {
-      "linux-x64": "59f83fc0678b95146ca539764d0c805bd2514b8588f198c1e835b26e54c05124"
+      "linux-x64": "89c5073418927ee71ac1de381eaba5ab69d599d615edc51b868d876e712dbf10"
     },
-    "engineVersion": "cloudru-vm 0.2.3-20260718",
+    "engineVersion": "cloudru-vm 0.2.6-20261020",
     "platformPackages": {
       "linux-x64": "@dzhechkov/cloudru-vm-linux-x64"
     }
@@ -49,19 +49,22 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "scripts": {
+    "test": "node --test 'test/*.test.mjs'"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/djd1m/dz-harness.git",
     "directory": "packages/@dzhechkov/cloudru-hub"
   },
-  "homepage": "https://github.com/djd1m/dz-harness/tree/main/packages/@dzhechkov/cloudru-hub#readme",
+  "homepage": "https://aicoding.space",
   "bugs": {
     "url": "https://github.com/djd1m/dz-harness/issues"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "test": "node --test 'test/*.test.mjs'"
   }
-}
+}

package/sbom.json

@@ -15,7 +15,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "edc0f1b076a22dc14b863bef8b287c1b9d8618a12b7ecf9f6eb0c497f74361f3"
+          "content": "d2be06e900ab3d02d367ff5d91129ef3faa9a16e1afac6fba8ae9cec4a51c322"
         }
       ]
     },
@@ -35,7 +35,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "504ce5cd5b6293b3606f861f31406ae89aa6fee45a03c9099d793aa5a456ced1"
+          "content": "c505a9bb7ab6f8d9fbe1cac64e22b12ec14f674f979af7120457b8ba49039484"
         }
       ]
     },
@@ -85,7 +85,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "13d6a3e87d767d0015f6b2af0223633fa99e49c69c9a8adcec8f6fce6e46d36e"
+          "content": "b1216e31ed28655ea99d9ef06d82d4d35d5499bad1ecadc8e7051e8c74bd7c97"
         }
       ]
     },
@@ -95,7 +95,17 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "56221fa8170f2b32ab6d3a907261badc07695f47ae9ac4adca4e43d2ea5ee06f"
+          "content": "c9f53d02b7ee06791eac22214ca91e999aeec2ee4dbd53b6a27dc46d4e5bcbc2"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "docs/HERMES-CODEX.md",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "08e1e83985c31b51aa053811b1b6a76fb1960323c5ccb8ae1d5fdd8b91b8df11"
         }
       ]
     },
@@ -105,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "092142c00295c54866330f2159a13284d04e2f35a749b32dff0ca4f2ab28ea54"
+          "content": "f043a370b9f23b2efc6c64702ab358ee168b6c9cd1b5d9efe4a9da287274e42c"
         }
       ]
     },
@@ -119,7 +129,7 @@
         },
         {
           "name": "dz:canonical-json-sha256-v2",
-          "value": "9586c2e63291e19031382f57b2f81d9a0f7d2917fc026e1e704f94b9108b5931"
+          "value": "671ebb618e9d0a939a047433791cd9a34e502339596d11a697b50fb32a0694ec"
         }
       ]
     },
@@ -139,7 +149,27 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "db981ad0078c80ba7a859057638a2576d7f02d87ca2891f8083a92a8147742dd"
+          "content": "af553e9261300eb46240212eb03b01ccc17234fed1a9f1587d5784f3bfacb5f4"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "src/credentials.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "21f074b4bf5b5ee9e893a2c1919cf4bb62f9fa05a0d7a1a8c04afc051ccb0e78"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "src/deploy-approval.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "5c1fba3d298df73ff82f28c72bc5199d23acc6dfc64022438874b0e3381c9394"
         }
       ]
     },
@@ -159,7 +189,27 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5d087b289aaf8cd2e1b4cffbd2227eb3bdc7264cddc0877561e08bc0ea6d6fd2"
+          "content": "c928db48febfb4a79884ce1830365a8302122a55fb5d6ada8e771c049396ca89"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "src/k8s-approval.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "014c2effd1e843d870ae1af4f93f5c82faff9972e9f6ca028ed39d47ec33ee3a"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "src/probe-child.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "0f7a0c1f6d0d033006ca816df49c24e69eb82aa6b70ec03491bce9e4d674bdd4"
         }
       ]
     },
@@ -173,6 +223,26 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "src/safe-mcp.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "4f95cfb9576c411232503b26053ece6d8d186e4b337beff9bd4afd249f74a014"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "src/toolsets.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "89229c882b6a3f5bb9ee542b31d1a40374b91879747582a3e82e8aadc72decb3"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "templates/.claude/hooks/cloudru-ssh-guard.cjs",
@@ -183,13 +253,33 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/billing-credentials.test.mjs",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "f2e1b05bdb6a6e811844ee19b0142daa02647b387f5d96b4a5d29bd34e3c985d"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "test/classification.test.mjs",
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "25290e9a8715d13670d617e23cb47c4c2d71b1506a8d98e5b682733b626a18b8"
+          "content": "026e3031180ce9227b4d31775b9c886b10ad0cb418ed0754aed75b12ded84e31"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "test/deploy-approval.test.mjs",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "d72e4363fd50d0fcc65fd23b40601516bd73368c3659f2a55a394c4d1ed3f85c"
         }
       ]
     },
@@ -199,7 +289,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9b83b2e2cbbee4ead33af61db840833ce4aa2dd0cf5a4448d72d5886098639c6"
+          "content": "3e6236f0cfb159dd73477b6243f6af536925968308085fd248df93932a2bebbf"
         }
       ]
     },
@@ -219,7 +309,27 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e986b29346672bf75b384ab6d8657265b8ecb8f62df6563dca317c1fc63fc8fc"
+          "content": "07fe729b0dc6955329d0a3121ce97d575582f8c6f2895e72d0c38175f82b52d2"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "test/k8s-approval.test.mjs",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "af04d1941fb7aed2cc51b05f65ffed1c440d4d23a7fb26e13261d45e07b0a1f8"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "test/mutation-registry-freshness.test.mjs",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "99cc5dd9f32ffbfbde09361940190f41b2efd682f687b3db67b5a3b943e66f47"
         }
       ]
     },
@@ -229,7 +339,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "23baf0c1c20afc5bbbfcd72ae9c553ce8a774c25328609e33f43e11cf4ca5581"
+          "content": "09b8fdc28bbe5df9b4cfd7d563c1acb479532157bbe1a99e909b3b370dd96630"
         }
       ]
     },
@@ -249,7 +359,17 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6b524f69c5ed03aaafab67e734e58092033423b86feade28ad03f516feba2380"
+          "content": "3b695381c2df4f5b592b377bd3ef5b3f3953af9f6f140600cfcddc975563bffc"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "test/safe-mcp.test.mjs",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "45406dabeee0635ede5cda3d2f4144c5c13886d624287fd223b01252d2859b87"
         }
       ]
     }

package/src/cli.js

@@ -6,6 +6,9 @@ const { spawn, spawnSync } = require('child_process');
 const { resolveEngine } = require('./resolve');
 const { loadClassification, loadSnapshot, coverageGaps } = require('./classification');
 const { install } = require('./install');
+const { runSafeMcp } = require('./safe-mcp');
+const { issueApproval } = require('./deploy-approval');
+const { issueK8sApproval } = require('./k8s-approval');
 const { compileSkill, writeCompiled } = require('./dialects');
 const PKG = require('../package.json');
 
@@ -21,14 +24,23 @@ Usage: cloudru-hub <command> [options]
 Commands:
   resolve [--json]         Locate the engine binary (env CLOUDRU_VM_BIN → ~/.cloudru-hub/config.json
                            enginePath → optional platform package) and verify its sha256 pin.
-  self-test [--json]       End-to-end local check: resolve → sha256 → engine version → live
-                           tools/list probe → golden-classification coverage. Exit 0 = all green.
+  self-test [--json]       Local check: resolve → sha256 → engine version → live tools/list
+                           → golden-classification coverage. Exit 0 = all green.
   mcp                      Run the resolved engine as an MCP stdio server (what .mcp.json points at).
-  install --target <t>     Emit the per-target integration per ADR-005 tiering:
-                           claude-code (full: .mcp.json + permission brake + PreToolUse veto, with an
-                           EXECUTED veto probe), codex (plan-only), agents-md|gemini (pointer-only),
-                           openclaude|opencode|cursor|windsurf|copilot (refused: DEGRADED until live probe).
-           [--dir <path>]  Project directory (default: cwd).  [--npx] use the npx form in .mcp.json.
+  mcp-safe [--toolsets <groups>]  Run a pinned MCP proxy; vm-deploy and k8s-deploy enable bounded deployment.
+  approve --plan-id <id> --max-monthly-rub <amount> [--site-sha256 <digest>]
+                           Authorize one exact VM plan for ten minutes within a RUB/month cap.
+                           Static sites require the artifact digest shown by deploy_plan.
+  k8s-approve --cluster-id <uuid> --namespace <name> --manifest <file> --manifest-sha256 <digest>
+                           Authorize one exact three-resource Snake manifest on an existing cluster.
+  install --target <t>     claude-code: permissions + executed hook probe;
+                           codex|opencode|pi: project MCP config using mcp-safe;
+                           hermes: guarded $HERMES_HOME/config.yaml entry using mcp-safe;
+                           openclaude|cursor|windsurf|copilot: refused pending live probe.
+           [--dir <path>]  Project directory (default: cwd). [--toolsets <groups>] defaults to
+                           inventory for safe hosts; all|compute|kubernetes|data|network|storage|billing|vm-deploy|k8s-deploy.
+                           [--hermes-home <dir>] overrides $HERMES_HOME for Hermes.
+                           [--npx] use the npx form in Claude .mcp.json.
   compile-skill --canonical <dir> --target <t> --out <dir>
                            Generate a target dialect of the canonical skill tree (ADR-006). The
                            canonical corpus is NOT shipped here; point --canonical at the skill/
@@ -53,8 +65,7 @@ function parseArgs(argv) {
 }
 
 function jsonRpcProbe(binPath, timeoutMs = 20_000) {
-  const req = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }) + '\n';
-  const r = spawnSync(binPath, ['mcp'], { input: req, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  const r = spawnSync(process.execPath, [require('path').join(__dirname, 'probe-child.js'), binPath], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
   if (r.error) return { error: String(r.error.message || r.error) };
   const line = String(r.stdout || '').split('\n').find((l) => l.trim().startsWith('{'));
   if (!line) return { error: 'engine produced no JSON-RPC response line' };
@@ -76,7 +87,7 @@ function cmdResolve(flags, write) {
   write(`source   ${r.source}`);
   write(`sha256   ${r.sha256}`);
   write(`pinned   ${r.pinned || '<no pin for ' + r.key + '>'}`);
-  write(`verified ${r.verified ? 'yes — matches the pinned baseline' : 'NO — not the pinned baseline (tolerated for env/config paths)'}`);
+  write(`verified ${r.verified ? 'yes — matches the pinned baseline' : 'NO — not the pinned baseline (resolution only; MCP launch refused)'}`);
   return 0;
 }
 
@@ -87,7 +98,11 @@ function cmdSelfTest(flags, write) {
   const r = resolveEngine();
   if (r.error) { step('resolve', false, r.error.split('\n')[0]); if (flags.has('json')) write(JSON.stringify(out, null, 2)); return 1; }
   step('resolve', true, `${r.path} (source: ${r.source})`);
-  step('sha256', true, `${r.sha256}${r.verified ? ' — MATCHES pinned baseline' : ' — no pin match (dev build?)'}`);
+  step('sha256', r.verified, `${r.sha256}${r.verified ? ' — MATCHES pinned baseline' : ' — DOES NOT MATCH pinned baseline'}`);
+  if (!r.verified) {
+    if (flags.has('json')) write(JSON.stringify(out, null, 2));
+    return 1;
+  }
 
   const ver = spawnSync(r.path, ['version'], { encoding: 'utf8', timeout: 10_000 });
   const verOk = ver.status === 0;
@@ -97,13 +112,13 @@ function cmdSelfTest(flags, write) {
   if (probe.error) { step('tools-list', false, probe.error); if (flags.has('json')) write(JSON.stringify(out, null, 2)); return 1; }
   const names = probe.tools.map((t) => t.name);
   const snap = loadSnapshot();
-  step('tools-list', true, `${names.length} tools live (snapshot: ${snap.toolCount})`);
+  step('tools-list', names.length === snap.toolCount, `${names.length} tools live (snapshot: ${snap.toolCount})`);
 
   const gaps = coverageGaps(names);
-  const gapsOk = gaps.unknown.length === 0;
+  const gapsOk = gaps.unknown.length === 0 && gaps.missing.length === 0;
   step('classification-coverage', gapsOk, gapsOk
     ? `every live tool is classified (${Object.keys(loadClassification().tools).length} golden entries)${gaps.missing.length ? `; ${gaps.missing.length} classified tool(s) absent live: ${gaps.missing.join(', ')}` : ''}`
-    : `UNCLASSIFIED live tools (deny-by-default — update data/tools-classification.json): ${gaps.unknown.join(', ')}`);
+    : `tool drift: unclassified=${gaps.unknown.join(', ') || '<none>'}; missing=${gaps.missing.join(', ') || '<none>'}`);
 
   out.ok = out.steps.every((s) => s.ok);
   if (flags.has('json')) write(JSON.stringify(out, null, 2));
@@ -114,6 +129,10 @@ function cmdSelfTest(flags, write) {
 function cmdMcp() {
   const r = resolveEngine();
   if (r.error) { process.stderr.write(r.error + '\n'); return 1; }
+  if (!r.verified) {
+    process.stderr.write(`cloudru-hub mcp: engine sha256 ${r.sha256} does not match pinned ${r.pinned || '<none>'}; refusing to launch\n`);
+    return 1;
+  }
   const child = spawn(r.path, ['mcp'], { stdio: 'inherit' });
   child.on('exit', (code, signal) => process.exit(signal ? 1 : code === null ? 1 : code));
   child.on('error', (e) => { process.stderr.write('cloudru-hub mcp: ' + e.message + '\n'); process.exit(1); });
@@ -139,10 +158,40 @@ function main(argv, write = (s) => process.stdout.write(s + '\n')) {
       const rc = cmdMcp();
       return rc === null ? null : rc;
     }
+    case 'mcp-safe':
+      return runSafeMcp({ toolsets: opts.get('toolsets') || 'all' });
+    case 'approve': {
+      const amount = Number(opts.get('max-monthly-rub'));
+      if (!opts.get('plan-id') || !opts.has('max-monthly-rub') || !Number.isFinite(amount) || amount < 0) {
+        write('cloudru-hub approve: --plan-id and non-negative --max-monthly-rub are required');
+        return 1;
+      }
+      try {
+        const approval = issueApproval(opts.get('plan-id'), amount, process.env, Date.now(), opts.get('site-sha256') || '');
+        write(flags.has('json') ? JSON.stringify(approval, null, 2) :
+          `approved ${approval.planId}: ${approval.vmName}, estimated ${approval.estimatedMonthlyRub} RUB/month (cap ${approval.maxMonthlyRub}); expires ${new Date(approval.expiresAt).toISOString()}${approval.staticSite ? `; static source ${approval.staticSite.source}, SHA-256 ${approval.staticSite.sha256} (${approval.staticSite.sizeBytes} bytes, ${approval.staticSite.files.length} files), ${approval.staticSite.ingress}; ${approval.staticSite.estimateScope}` : ''}`);
+        return 0;
+      } catch (error) {
+        write(`cloudru-hub approve: ${error.message}`);
+        return 1;
+      }
+    }
+    case 'k8s-approve': {
+      try {
+        const approval = issueK8sApproval(opts.get('cluster-id'), opts.get('namespace'),
+          opts.get('manifest'), opts.get('manifest-sha256'));
+        write(flags.has('json') ? JSON.stringify(approval, null, 2) :
+          `approved ${approval.approvalId}: cluster ${approval.clusterId}, namespace ${approval.namespace}, SHA-256 ${approval.manifestSha256}; expires ${new Date(approval.expiresAt).toISOString()}`);
+        return 0;
+      } catch (error) {
+        write(`cloudru-hub k8s-approve: ${error.message}`);
+        return 1;
+      }
+    }
     case 'install': {
       const target = opts.get('target');
       if (!target) { write('cloudru-hub install: --target is required (claude-code|codex|agents-md|gemini|…)'); return 1; }
-      const res = install(target, opts.get('dir') || process.cwd(), { npx: flags.has('npx') });
+      const res = install(target, opts.get('dir') || process.cwd(), { npx: flags.has('npx'), toolsets: opts.get('toolsets') || 'inventory', hermesHome: opts.get('hermes-home') });
       for (const line of res.lines) write(line);
       return res.code;
     }

package/src/credentials.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const UUID = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i;
+
+const ZONES = Object.freeze({
+  'ru.AZ-1': '7c99a597-8516-494f-a2c7-d7377048681e',
+  'ru.AZ-2': '479a4ab3-3ff3-4972-95c5-7610bac5c0bb',
+  'ru.AZ-3': '2c63c482-2532-4bba-8c9b-70ea330507bf',
+});
+
+function credentialsPath(env = process.env) {
+  return env.CLOUDRU_HUB_CREDENTIALS || path.join(os.homedir(), '.config', 'cloudru-hub', 'credentials.json');
+}
+
+function readCredentials(env = process.env) {
+  const file = credentialsPath(env);
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink()) throw new Error('credentials must be a regular file');
+  if ((st.mode & 0o077) !== 0) throw new Error('credentials permissions must be 0600');
+  if (typeof process.getuid === 'function' && st.uid !== process.getuid()) throw new Error('credentials owner differs from MCP process');
+  if (st.size > 65536) throw new Error('credentials file is too large');
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { throw new Error('credentials file is not valid JSON'); }
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== 'object') throw new Error('credentials JSON must be an object');
+  for (const key of ['key_id', 'secret', 'project_id']) {
+    if (typeof parsed[key] !== 'string' || !parsed[key].trim()) throw new Error(`credentials ${key} is required`);
+    if (/[\r\n\0]/.test(parsed[key])) throw new Error(`credentials ${key} contains a control character`);
+  }
+  if (parsed.agreement_id !== undefined &&
+      (typeof parsed.agreement_id !== 'string' || !parsed.agreement_id.trim() || /[\r\n\0]/.test(parsed.agreement_id))) {
+    throw new Error('credentials agreement_id must be a non-empty string without control characters');
+  }
+  if (!UUID.test(parsed.project_id)) throw new Error('credentials project_id must be a UUID');
+  const region = parsed.region || 'ru.AZ-2';
+  const zone = ZONES[region] || region;
+  if (!UUID.test(zone)) throw new Error('credentials region must be a known zone or UUID');
+  return {
+    path: file,
+    projectId: parsed.project_id,
+    env: {
+      CLOUDRU_KEY_ID: parsed.key_id,
+      CLOUDRU_SECRET: parsed.secret,
+      CLOUDRU_PROJECT_ID: parsed.project_id,
+      CLOUDRU_REGION: zone,
+      ...(parsed.agreement_id === undefined ? {} : { CLOUDRU_AGREEMENT_ID: parsed.agreement_id.trim() }),
+    },
+  };
+}
+
+function readOptionalCredentials(env = process.env) {
+  // An explicit path must fail loudly when unreadable. Without one, retain
+  // environment-only billing setups that have no default credential file.
+  if (!env.CLOUDRU_HUB_CREDENTIALS && !fs.existsSync(credentialsPath(env))) return null;
+  return readCredentials(env);
+}
+
+module.exports = { credentialsPath, readCredentials, readOptionalCredentials, ZONES, UUID };

package/src/deploy-approval.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { readCredentials, UUID } = require('./credentials');
+
+const PLAN_ID = /^plan-[0-9a-f]{12}$/;
+
+function stateRoot(env = process.env) { return env.CLOUDRU_VM_HOME || os.homedir(); }
+function approvalRoot(env = process.env) { return env.CLOUDRU_HUB_APPROVALS || path.join(os.homedir(), '.config', 'cloudru-hub', 'approvals'); }
+function planPath(id, env = process.env) {
+  if (!PLAN_ID.test(id)) throw new Error('invalid plan_id');
+  return path.join(stateRoot(env), '.cloudru-vm', 'plans', `${id}.json`);
+}
+function readPlan(id, env = process.env, now = Date.now()) {
+  const file = planPath(id, env);
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink() || st.size > 65536) throw new Error('plan file is not a bounded regular file');
+  const raw = fs.readFileSync(file);
+  const plan = JSON.parse(raw);
+  if (plan.plan_id !== id || !UUID.test(plan.project_id || '')) throw new Error('plan identity or project is invalid');
+  const expires = Date.parse(plan.expires_at);
+  if (!Number.isFinite(expires) || expires <= now) throw new Error('plan expired');
+  const price = plan.cost && plan.cost.total_monthly_rub;
+  if (!plan.cost || plan.cost.currency !== 'RUB' || !Number.isFinite(price) || price < 0) throw new Error('plan cost is not a finite RUB estimate');
+  if (typeof plan.vm?.name !== 'string' || !plan.vm.name) throw new Error('plan VM name is invalid');
+  if (!plan.static_site && (typeof plan.ssh?.login !== 'string' || !plan.ssh.login)) throw new Error('plan SSH login is invalid');
+  if (plan.static_site) {
+    const site = plan.static_site;
+    if (!/^[0-9a-f]{64}$/.test(site.sha256 || '') || !Number.isSafeInteger(site.size_bytes) || site.size_bytes < 1 || site.size_bytes > 20 * 1024 ||
+        typeof site.source_base64 !== 'string' || site.source_base64.length > 28 * 1024 ||
+        !Array.isArray(site.files) || site.files.length < 1 || site.files.length > 32 ||
+        !Array.isArray(plan.ports) || plan.ports.length !== 1 || plan.ports[0] !== 80 || plan.network?.floating_ip !== true ||
+        typeof plan.network?.attach_fip_id !== 'string' || !UUID.test(plan.network.attach_fip_id)) {
+      throw new Error('static-site plan artifact or network scope is invalid');
+    }
+  }
+  return { plan, hash: crypto.createHash('sha256').update(raw).digest('hex'), price, expires };
+}
+function approvalPath(id, env = process.env) { return path.join(approvalRoot(env), `${id}.json`); }
+function ensurePrivateDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const st = fs.lstatSync(dir);
+  if (!st.isDirectory() || st.isSymbolicLink() || (st.mode & 0o077) !== 0) throw new Error('approval directory must be private (0700)');
+}
+function readPrivateJson(file) {
+  const st = fs.lstatSync(file);
+  if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077) !== 0 || st.size > 65536 ||
+      (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 issueApproval(id, maxMonthlyRub, env = process.env, now = Date.now(), reviewedSiteSha256 = '') {
+  const { plan, hash, price, expires } = readPlan(id, env, now);
+  if (plan.static_site && reviewedSiteSha256 !== plan.static_site.sha256) {
+    throw new Error('static-site approval requires --site-sha256 matching the reviewed artifact');
+  }
+  const credentials = readCredentials(env);
+  if (credentials.projectId !== plan.project_id) throw new Error('plan project differs from credentials project');
+  if (!Number.isFinite(maxMonthlyRub) || maxMonthlyRub < price) throw new Error('monthly cost exceeds operator cap');
+  const root = approvalRoot(env);
+  ensurePrivateDir(root);
+  const record = {
+    planId: id,
+    planHash: hash,
+    projectId: plan.project_id,
+    vmName: plan.vm.name,
+    sshUser: plan.ssh?.login || '',
+    siteMode: !!plan.static_site,
+    maxMonthlyRub,
+    issuedAt: now,
+    expiresAt: Math.min(expires, now + 10 * 60_000),
+  };
+  fs.writeFileSync(approvalPath(id, env), JSON.stringify(record) + '\n', { flag: 'wx', mode: 0o600 });
+  return { planId: id, projectId: record.projectId, vmName: record.vmName, estimatedMonthlyRub: price, maxMonthlyRub, expiresAt: record.expiresAt,
+    ...(plan.static_site ? { staticSite: { source: plan.static_site.source, sha256: plan.static_site.sha256, sizeBytes: plan.static_site.size_bytes,
+      files: plan.static_site.files.map((file) => ({ path: file.path, sha256: file.sha256, sizeBytes: file.size_bytes })),
+      ingress: 'dedicated security group: TCP 80 from 0.0.0.0/0', estimateScope: 'compute and disk only; public IP charges excluded' } } : {}) };
+}
+
+function consumeApproval(id, env = process.env, now = Date.now()) {
+  const { plan, hash, price } = readPlan(id, env, now);
+  const credentials = readCredentials(env);
+  const file = approvalPath(id, env);
+  const a = readPrivateJson(file);
+  if (a.planId !== id || a.planHash !== hash || a.projectId !== plan.project_id || a.projectId !== credentials.projectId || a.siteMode !== !!plan.static_site ||
+      a.vmName !== plan.vm.name || !Number.isFinite(a.maxMonthlyRub) || price > a.maxMonthlyRub ||
+      !Number.isFinite(a.expiresAt) || a.expiresAt <= now) throw new Error('approval does not match current plan, project, cost or time');
+  const spent = path.join(approvalRoot(env), `${id}.used-${crypto.randomBytes(8).toString('hex')}.json`);
+  fs.renameSync(file, spent); // one caller consumes the pending path; a replay cannot.
+  return a;
+}
+
+function recordDeployedVM(approval, result, env = process.env, now = Date.now()) {
+  const vmId = result && result.vm_id;
+  if (!UUID.test(vmId || '') || result.status !== 'running') throw new Error('deploy did not return a running VM UUID');
+  const root = approvalRoot(env);
+  ensurePrivateDir(root);
+  const session = { planId: approval.planId, projectId: approval.projectId, vmId, sshUser: approval.sshUser, expiresAt: now + 2 * 60 * 60_000 };
+  fs.writeFileSync(path.join(root, `${approval.planId}.session.json`), JSON.stringify(session) + '\n', { flag: 'wx', mode: 0o600 });
+  return session;
+}
+
+function approvedVM(requestedId, env = process.env, now = Date.now()) {
+  const root = approvalRoot(env);
+  if (!fs.existsSync(root)) throw new Error('no approved deployment session');
+  ensurePrivateDir(root);
+  const sessions = fs.readdirSync(root).filter((name) => /^plan-[0-9a-f]{12}\.session\.json$/.test(name));
+  const credentials = readCredentials(env);
+  if (requestedId && !UUID.test(requestedId)) throw new Error('vm_exec requires an approved VM UUID');
+  const live = sessions.map((name) => readPrivateJson(path.join(root, name)))
+    .filter((s) => s.expiresAt > now && s.projectId === credentials.projectId && UUID.test(s.vmId || ''));
+  const matching = requestedId ? live.filter((s) => s.vmId === requestedId) : live;
+  if (matching.length !== 1) throw new Error('vm_exec requires exactly one matching active approved VM session');
+  return matching[0];
+}
+
+module.exports = { stateRoot, approvalRoot, planPath, readPlan, issueApproval, consumeApproval, recordDeployedVM, approvedVM };