@js-eyes/protocol 2.6.0 → 2.6.2

package/extra-integrity.js

@@ -0,0 +1,199 @@
+'use strict';
+
+// extra-integrity: optional snapshot-and-verify layer for extraSkillDirs.
+//
+// Gated by `security.verifyExtraSkillDirs` (default false for 2.6.1
+// compatibility). When enabled:
+//   * `js-eyes skills link <path>` calls `snapshotExtraDir(path)` to record a
+//     per-file sha256 map under ~/.js-eyes/state/extras/<hash>.json (the state
+//     file lives outside the external dir so js-eyes never writes to it);
+//   * the plugin's SkillRegistry calls `verifyExtraDir(path)` before loading
+//     each extra; on drift the load is refused and the operator is told to
+//     run `js-eyes skills relink <path>` after reviewing the changes.
+//
+// ClawHub / OpenClaw flagged extraSkillDirs as "read-only but bypass integrity
+// verification"; this module closes that gap without breaking the default
+// behaviour. See SECURITY_SCAN_NOTES.md.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { ensureDir } = require('./fs-io');
+
+const STATE_DIR_NAME = 'state';
+const EXTRAS_DIR_NAME = 'extras';
+const SNAPSHOT_VERSION = 1;
+
+function sha1(text) {
+  return crypto.createHash('sha1').update(text).digest('hex');
+}
+
+function sha256File(filePath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+function resolveBaseDir(options = {}) {
+  if (options.baseDir) return path.resolve(options.baseDir);
+  if (process.env.JS_EYES_HOME) return path.resolve(process.env.JS_EYES_HOME);
+  return path.join(options.home || os.homedir(), '.js-eyes');
+}
+
+function getSnapshotPath(absPath, options = {}) {
+  if (!absPath || typeof absPath !== 'string') {
+    throw new Error('getSnapshotPath: absPath required');
+  }
+  const baseDir = resolveBaseDir(options);
+  const key = sha1(path.resolve(absPath));
+  return path.join(baseDir, STATE_DIR_NAME, EXTRAS_DIR_NAME, `${key}.json`);
+}
+
+function listFilesRecursive(dir) {
+  const out = [];
+  function walk(current) {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      const rel = path.relative(dir, full);
+      if (rel.split(path.sep)[0] === 'node_modules') continue;
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        out.push(rel.split(path.sep).join('/'));
+      }
+    }
+  }
+  walk(dir);
+  return out.sort();
+}
+
+function buildFileMap(absPath) {
+  const files = {};
+  for (const rel of listFilesRecursive(absPath)) {
+    const full = path.join(absPath, rel);
+    try {
+      files[rel] = sha256File(full);
+    } catch (_) {
+      // Skip unreadable files; they'll appear as missing in verify.
+    }
+  }
+  return files;
+}
+
+function writeSnapshot(absPath, snapshot, options = {}) {
+  const target = getSnapshotPath(absPath, options);
+  ensureDir(path.dirname(target));
+  fs.writeFileSync(target, JSON.stringify(snapshot, null, 2) + '\n', 'utf8');
+  try { fs.chmodSync(target, 0o600); } catch (_) { /* best-effort on POSIX */ }
+  return target;
+}
+
+function readSnapshot(absPath, options = {}) {
+  const target = getSnapshotPath(absPath, options);
+  if (!fs.existsSync(target)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(target, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function snapshotExtraDir(absPath, options = {}) {
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`snapshotExtraDir: path does not exist: ${absPath}`);
+  }
+  const snapshot = {
+    version: SNAPSHOT_VERSION,
+    path: path.resolve(absPath),
+    createdAt: new Date().toISOString(),
+    files: buildFileMap(absPath),
+  };
+  const snapshotPath = writeSnapshot(absPath, snapshot, options);
+  return { snapshot, snapshotPath };
+}
+
+function verifyExtraDir(absPath, options = {}) {
+  const snapshot = readSnapshot(absPath, options);
+  if (!snapshot || !snapshot.files) {
+    return {
+      ok: false,
+      hasSnapshot: false,
+      drifted: [],
+      missing: [],
+      extra: [],
+      checked: 0,
+    };
+  }
+
+  const expected = snapshot.files;
+  const expectedKeys = Object.keys(expected);
+  const actual = buildFileMap(absPath);
+
+  const drifted = [];
+  const missing = [];
+  for (const rel of expectedKeys) {
+    if (!Object.prototype.hasOwnProperty.call(actual, rel)) {
+      missing.push(rel);
+      continue;
+    }
+    if (actual[rel] !== expected[rel]) {
+      drifted.push(rel);
+    }
+  }
+  const extra = Object.keys(actual).filter(
+    (rel) => !Object.prototype.hasOwnProperty.call(expected, rel),
+  );
+
+  return {
+    ok: drifted.length === 0 && missing.length === 0 && extra.length === 0,
+    hasSnapshot: true,
+    drifted,
+    missing,
+    extra,
+    checked: expectedKeys.length,
+    snapshotCreatedAt: snapshot.createdAt || null,
+  };
+}
+
+function clearSnapshotForExtraDir(absPath, options = {}) {
+  const target = getSnapshotPath(absPath, options);
+  if (fs.existsSync(target)) {
+    try { fs.rmSync(target, { force: true }); } catch (_) { /* best-effort */ }
+    return true;
+  }
+  return false;
+}
+
+// Returns one of: 'verified' | 'drifted' | 'missing-snapshot' | 'off' | 'error'.
+// `off` means the global toggle is disabled.
+function classifyExtraDir(absPath, { enabled, options = {} } = {}) {
+  if (!enabled) return { state: 'off' };
+  let result;
+  try {
+    result = verifyExtraDir(absPath, options);
+  } catch (error) {
+    return { state: 'error', error: error.message };
+  }
+  if (!result.hasSnapshot) return { state: 'missing-snapshot', detail: result };
+  if (result.ok) return { state: 'verified', detail: result };
+  return { state: 'drifted', detail: result };
+}
+
+module.exports = {
+  SNAPSHOT_VERSION,
+  getSnapshotPath,
+  snapshotExtraDir,
+  verifyExtraDir,
+  clearSnapshotForExtraDir,
+  classifyExtraDir,
+  // Exposed for tests only.
+  _internals: { buildFileMap, listFilesRecursive, resolveBaseDir },
+};

package/fs-io.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// fs-io: pure filesystem helpers.
+//
+// Scoped deliberately: the functions here do local-only disk I/O and JSON
+// parsing. They never touch the network, and this module MUST NOT import
+// `ws`, `http`, `https`, `net`, or any network helper. The invariant is
+// verified by test/import-boundaries.test.js.
+//
+// See SECURITY_SCAN_NOTES.md ("File read combined with network send") for
+// the reason this module is kept separate from skills.js.
+
+const fs = require('fs');
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function safeStat(target) {
+  try {
+    return fs.statSync(target);
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = {
+  ensureDir,
+  readJson,
+  safeStat,
+};

package/index.js

@@ -69,6 +69,10 @@ const DEFAULT_SECURITY_CONFIG = Object.freeze({
   allowRemoteBind: false,
   allowRawEval: false,
   requireLockfile: true,
+  // 2.6.2 opt-in integrity checks for extraSkillDirs. Default false keeps
+  // behaviour identical to 2.6.1; flip to true (or run
+  // `js-eyes skills link`/`relink` with the flag enabled) to start verifying.
+  verifyExtraSkillDirs: false,
   enforcement: 'soft',
   taskOrigin: { ...DEFAULT_TASK_ORIGIN_CONFIG, sources: DEFAULT_TASK_ORIGIN_CONFIG.sources.slice() },
   egressAllowlist: [],

package/openclaw-paths.js

@@ -0,0 +1,33 @@
+'use strict';
+
+// openclaw-paths: OpenClaw state/config path resolution.
+//
+// Intentionally lives in its own module so the `process.env` reads that pick
+// up OPENCLAW_CONFIG_PATH / OPENCLAW_STATE_DIR / OPENCLAW_HOME never sit in the
+// same file as network clients (see SECURITY_SCAN_NOTES.md, "Environment
+// variable access combined with network send"). This file MUST NOT import
+// `ws`, `http`, `https`, `net`, or any network helper — that invariant is
+// verified by test/import-boundaries.test.js.
+
+const os = require('os');
+const path = require('path');
+
+function getOpenClawConfigPath(options = {}) {
+  const env = options.env || process.env;
+  const home = options.home || os.homedir();
+
+  if (env.OPENCLAW_CONFIG_PATH) {
+    return path.resolve(env.OPENCLAW_CONFIG_PATH);
+  }
+  if (env.OPENCLAW_STATE_DIR) {
+    return path.resolve(env.OPENCLAW_STATE_DIR, 'openclaw.json');
+  }
+  if (env.OPENCLAW_HOME) {
+    return path.resolve(env.OPENCLAW_HOME, '.openclaw', 'openclaw.json');
+  }
+  return path.join(home, '.openclaw', 'openclaw.json');
+}
+
+module.exports = {
+  getOpenClawConfigPath,
+};

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@js-eyes/protocol",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "Shared protocol constants for JS Eyes runtime packages",
   "main": "index.js",
   "files": [
     "index.js",
     "skills.js",
-    "zip-extract.js"
+    "zip-extract.js",
+    "fs-io.js",
+    "safe-npm.js",
+    "openclaw-paths.js",
+    "extra-integrity.js",
+    "skill-registry.js",
+    "skill-runner.js",
+    "registry-client.js"
   ],
   "license": "MIT",
   "author": "imjszhang <ortle3x3@gmail.com>",

package/registry-client.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// registry-client: the single place in @js-eyes/protocol that talks to the
+// ClawHub / custom skills registry over HTTP.
+//
+// Kept separate from skills.js / fs-io.js so the scanner never sees `fetch(…)`
+// co-located with `fs.readFileSync(…)` or `fs.createReadStream(…)`. The
+// invariant is enforced by test/import-boundaries.test.js (inverse direction:
+// `fs-io.js` / `openclaw-paths.js` MUST NOT import anything network-capable,
+// and vice-versa this module MUST NOT re-introduce `fs.readFile*` /
+// `fs.createReadStream*`).
+//
+// See SECURITY_SCAN_NOTES.md ("File read combined with network send").
+
+async function fetchSkillsRegistry(registryUrl) {
+  const response = await fetch(registryUrl, {
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+// downloadBuffer: attempts a list of candidate URLs in order and returns the
+// first successful body as a Buffer. Lives next to fetchSkillsRegistry so the
+// skill-install flow's network I/O is consolidated in this module — skills.js
+// just calls it and then hashes / validates / writes the bytes through
+// fs-io.js helpers.
+async function downloadBuffer(urls, logger = console) {
+  let lastError = null;
+  for (const url of urls) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        const buf = Buffer.from(await response.arrayBuffer());
+        return { buffer: buf, url };
+      }
+      lastError = new Error(`HTTP ${response.status} (${url})`);
+    } catch (error) {
+      lastError = error;
+    }
+    if (logger && typeof logger.warn === 'function') {
+      logger.warn(`[js-eyes] Download failed (${url}): ${lastError?.message || 'unknown'}`);
+    }
+  }
+  throw lastError || new Error('Download failed for all URLs');
+}
+
+module.exports = { fetchSkillsRegistry, downloadBuffer };

package/safe-npm.js

@@ -0,0 +1,150 @@
+'use strict';
+
+// safe-npm: the only place in this package that invokes child_process.
+//
+// Design constraints (see SECURITY_SCAN_NOTES.md, "Shell command execution"):
+//   * subcommand is chosen from an immutable whitelist — callers can only
+//     select by name, never by passing a string;
+//   * every argv entry is a constant (no string concatenation from user input);
+//   * spawnSync is called with `shell: false` and `windowsHide: true`;
+//   * the child env is built from a small whitelist, so secrets in
+//     process.env (tokens, OAuth state, etc.) never leak into the npm run;
+//   * postinstall scripts are disabled unless the caller explicitly opts in.
+//
+// The single allowed binary name is `npm`. No wildcards, no PATHEXT, no shell
+// meta-characters: Node's child_process with shell=false treats the argv as a
+// literal argument vector.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ALLOWED_SUBCOMMANDS = Object.freeze({
+  ci: Object.freeze(['ci', '--no-audit', '--no-fund']),
+  install: Object.freeze(['install', '--no-audit', '--no-fund']),
+});
+
+const SAFE_ENV_KEYS = Object.freeze([
+  'PATH',
+  'HOME',
+  'USERPROFILE',
+  'APPDATA',
+  'LOCALAPPDATA',
+  'SystemRoot',
+  'SYSTEMROOT',
+  'COMSPEC',
+  'TEMP',
+  'TMP',
+  'TMPDIR',
+  'LANG',
+  'LC_ALL',
+  'LC_CTYPE',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'PATHEXT',
+]);
+
+function buildSafeEnv(sourceEnv, extra = {}) {
+  const src = sourceEnv || process.env;
+  const next = {};
+  for (const key of SAFE_ENV_KEYS) {
+    if (src[key] !== undefined) next[key] = src[key];
+  }
+  for (const [key, value] of Object.entries(src)) {
+    if (key.startsWith('npm_config_')) next[key] = value;
+  }
+  for (const [key, value] of Object.entries(extra || {})) {
+    if (value !== undefined) next[key] = value;
+  }
+  return next;
+}
+
+function detectPackageManager(targetDir) {
+  if (fs.existsSync(path.join(targetDir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(targetDir, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(targetDir, 'package-lock.json'))) return 'npm';
+  return null;
+}
+
+function runNpm(subcommand, targetDir, options = {}) {
+  if (!Object.prototype.hasOwnProperty.call(ALLOWED_SUBCOMMANDS, subcommand)) {
+    throw new Error(`safe-npm: subcommand "${subcommand}" is not in the allowlist`);
+  }
+  if (typeof targetDir !== 'string' || !targetDir) {
+    throw new Error('safe-npm: targetDir must be a non-empty string');
+  }
+
+  const baseArgs = ALLOWED_SUBCOMMANDS[subcommand].slice();
+  const allowPostinstall = Boolean(options.allowPostinstall);
+  if (!allowPostinstall) baseArgs.push('--ignore-scripts');
+
+  const childEnv = buildSafeEnv(options.env || process.env, {
+    npm_config_ignore_scripts: allowPostinstall ? 'false' : 'true',
+  });
+
+  const result = spawnSync('npm', baseArgs, {
+    cwd: targetDir,
+    stdio: options.stdio || 'pipe',
+    shell: false,
+    windowsHide: true,
+    env: childEnv,
+  });
+
+  return { result, args: baseArgs };
+}
+
+function safeNpmCi(targetDir, options = {}) {
+  const { result, args } = runNpm('ci', targetDir, options);
+  if (result.status !== 0) {
+    const stderr = result.stderr ? String(result.stderr) : '';
+    throw new Error(`npm ${args.join(' ')} 失败 (status=${result.status}): ${stderr.slice(0, 500)}`);
+  }
+  return { ran: true, manager: 'npm', args };
+}
+
+function safeNpmInstall(targetDir, options = {}) {
+  const { result, args } = runNpm('install', targetDir, options);
+  if (result.status !== 0) {
+    const stderr = result.stderr ? String(result.stderr) : '';
+    throw new Error(`npm ${args.join(' ')} 失败 (status=${result.status}): ${stderr.slice(0, 500)}`);
+  }
+  return { ran: true, manager: 'npm', args };
+}
+
+function installSkillDependencies(targetDir, options = {}) {
+  const pkgJson = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(pkgJson)) return { ran: false, manager: null };
+
+  const requireLockfile = options.requireLockfile !== false;
+  const manager = detectPackageManager(targetDir);
+
+  if (requireLockfile && manager !== 'npm') {
+    throw new Error('安装拒绝执行：缺少 package-lock.json（开启 security.requireLockfile=false 可放宽）');
+  }
+
+  const runOptions = {
+    allowPostinstall: Boolean(options.allowPostinstall),
+    stdio: options.stdio,
+    env: options.env,
+  };
+
+  const outcome = manager === 'npm'
+    ? safeNpmCi(targetDir, runOptions)
+    : safeNpmInstall(targetDir, runOptions);
+
+  return {
+    ran: true,
+    manager: outcome.manager,
+    allowPostinstall: runOptions.allowPostinstall,
+  };
+}
+
+module.exports = {
+  ALLOWED_SUBCOMMANDS,
+  SAFE_ENV_KEYS,
+  buildSafeEnv,
+  detectPackageManager,
+  safeNpmCi,
+  safeNpmInstall,
+  installSkillDependencies,
+};