workspec 1.1.0 → 1.1.1

package/README.md

@@ -31,14 +31,17 @@ Validate:
 ```bash
 workspec validate path/to/file.workspec.json
 workspec validate path/to/file.workspec.json --json
-workspec validate -custom path/to/simulation-validator-custom.js path/to/file.workspec.json
-workspec validate path/to/file.workspec.json --custom path/to/custom-validator.js --custom-catalog path/to/metrics-catalog-custom.json
+workspec validate -custom path/to/simulation-validator-custom.js path/to/file.workspec.json -y
+workspec validate path/to/file.workspec.json --custom path/to/custom-validator.js --custom-catalog path/to/metrics-catalog-custom.json -y
 ```
 
 `-custom/--custom` supports:
 - Metrics Editor-style `validate*` functions in a plain `.js` file
 - Node-style exports (`module.exports = function (...) { ... }` or `module.exports.validate = ...`)
 
+Custom validators run user-provided JavaScript and may be dangerous/malicious. The CLI now requires an interactive `Y` confirmation before custom validation executes. Use `-y` / `--yes` to skip the confirmation (required in non-interactive runs like CI).
+Custom validation execution is isolated in a subprocess with a hard timeout, and catalog/discovered entry points are restricted to `validate*` function names.
+
 If `--custom-catalog` is omitted, the CLI auto-loads `metrics-catalog-custom.json` from the custom validator file's folder when present.
 
 Migrate (Previous UAW Syntax -> WorkSpec v1.0.0):

package/bin/workspec.js

@@ -3,6 +3,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const readline = require('readline');
 
 const validator = require(path.join(__dirname, '..', 'workspec-validator.js'));
 const migrator = require(path.join(__dirname, '..', 'workspec-migrate-v1-to-v2.js'));
@@ -13,7 +14,7 @@ function printHelp(exitCode = 0) {
         'workspec - WorkSpec v1.1.0 CLI',
         '',
         'Usage:',
-        '  workspec validate <file.workspec.json> [-custom <validator.js>] [--custom-catalog <catalog.json>] [--json]',
+        '  workspec validate <file.workspec.json> [-custom <validator.js>] [--custom-catalog <catalog.json>] [--json] [-y]',
         '  workspec migrate <file.json> --out <output.json> [--schema]',
         '  workspec format <file.json> [--write] [--out <output.json>]',
         '',
@@ -26,6 +27,7 @@ function printHelp(exitCode = 0) {
         '  -custom <path>  Run custom validator code (Metrics Editor compatible).',
         '  --custom <path> Same as -custom.',
         '  --custom-catalog <path> Optional metrics-catalog JSON for custom metrics.',
+        '  -y, --yes      Skip custom validation safety confirmation prompt.',
         '  --json          Print machine-readable problems JSON (validate only).',
         '  --out <path>    Output path (migrate/format).',
         '  --write         Write output (format only; defaults to stdout).',
@@ -71,6 +73,10 @@ function parseArgs(argv) {
             result.flags.json = true;
             continue;
         }
+        if (arg === '--yes' || arg === '-y') {
+            result.flags.yes = true;
+            continue;
+        }
         if (arg === '--custom' || arg === '-custom') {
             result.flags.custom = args.shift() || '';
             continue;
@@ -119,6 +125,49 @@ function hasErrors(problems) {
     return problems.some((p) => p && p.severity === 'error');
 }
 
+function promptConfirm(message) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+        rl.question(message, (answer) => {
+            rl.close();
+            resolve(String(answer || '').trim());
+        });
+    });
+}
+
+async function confirmCustomValidation(flags) {
+    if (!flags.custom || flags.yes) {
+        return true;
+    }
+
+    const warning = [
+        'Custom validation runs JavaScript from the provided script.',
+        'Only continue if you trust the author of this custom validation file.',
+        'Continue custom validation? [Y/N] '
+    ].join('\n');
+
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        process.stderr.write(
+            'Custom validation confirmation is required in interactive mode. ' +
+            'Re-run with -y/--yes to skip confirmation.\n'
+        );
+        process.exitCode = 2;
+        return false;
+    }
+
+    const response = await promptConfirm(warning);
+    if (response.toUpperCase() !== 'Y') {
+        process.stderr.write('Custom validation cancelled.\n');
+        process.exitCode = 2;
+        return false;
+    }
+
+    return true;
+}
+
 async function readInput(filePath) {
     if (!filePath || filePath === '-') {
         return readStdin();
@@ -145,6 +194,10 @@ async function handleValidate(filePath, flags) {
         return;
     }
 
+    if (!(await confirmCustomValidation(flags))) {
+        return;
+    }
+
     let raw;
     try {
         raw = await readInput(filePath);

package/custom-validation-runner.js

@@ -2,11 +2,16 @@
 
 const fs = require('fs');
 const path = require('path');
-const vm = require('vm');
+const { spawn } = require('child_process');
 
 const WORKSPEC_NAMESPACE = 'https://universalautomation.wiki/workspec';
 const EXECUTION_TIMEOUT_MS = 5000;
+const SUBPROCESS_GRACE_MS = 1000;
+const MAX_SUBPROCESS_OUTPUT_BYTES = 1024 * 1024;
 const FUNCTION_NAME_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const ALLOWED_VALIDATE_FUNCTION_RE = /^validate[A-Za-z0-9_$]*$/;
+const VALIDATOR_EXTENSIONS = new Set(['.js', '.cjs']);
+const CATALOG_EXTENSIONS = new Set(['.json']);
 
 function isPlainObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -131,12 +136,6 @@ function normalizeProblems(value, fallbackMetricId) {
     return single ? [single] : [];
 }
 
-function resolvePath(inputPath) {
-    if (!inputPath) return '';
-    if (path.isAbsolute(inputPath)) return inputPath;
-    return path.resolve(process.cwd(), inputPath);
-}
-
 function getSimulation(documentValue) {
     if (!isPlainObject(documentValue)) return {};
     return isPlainObject(documentValue.simulation) ? documentValue.simulation : documentValue;
@@ -169,7 +168,7 @@ function discoverValidationFunctions(sourceCode) {
         let match;
         while ((match = re.exec(sourceCode)) !== null) {
             const name = safeTrim(match[1]);
-            if (name && /^validate[A-Za-z0-9_$]*/.test(name)) {
+            if (name && ALLOWED_VALIDATE_FUNCTION_RE.test(name)) {
                 names.add(name);
             }
         }
@@ -217,10 +216,9 @@ function parseCatalog(catalogRawText, catalogPath) {
 }
 
 function loadMetricsCatalog(customValidatorPath, explicitCatalogPath) {
-    const resolvedExplicit = resolvePath(explicitCatalogPath);
-    if (resolvedExplicit) {
-        const raw = fs.readFileSync(resolvedExplicit, 'utf8');
-        return parseCatalog(raw, resolvedExplicit);
+    if (explicitCatalogPath) {
+        const raw = fs.readFileSync(explicitCatalogPath, 'utf8');
+        return parseCatalog(raw, explicitCatalogPath);
     }
 
     const sidecarPath = path.join(path.dirname(customValidatorPath), 'metrics-catalog-custom.json');
@@ -286,24 +284,58 @@ async function runExportedValidation(exportedValue, helpers, problems) {
     return handled;
 }
 
-function runBrowserStyleValidation(sourceCode, metrics, helpers, customValidatorPath, problems) {
-    const sandbox = {
-        simulation: helpers.simulation,
-        addResult: helpers.addResult,
-        addProblem: helpers.addProblem,
-        _timeToMinutes: helpers._timeToMinutes,
-        console: {
-            log: (...args) => console.log('[workspec custom]', ...args),
-            warn: (...args) => console.warn('[workspec custom]', ...args),
-            error: (...args) => console.error('[workspec custom]', ...args)
-        },
-        require: undefined,
-        process: undefined,
-        module: undefined,
-        exports: undefined,
-        Buffer: undefined
+function buildInstrumentedSource(sourceCode, captureFunctionNames) {
+    const lines = [
+        '"use strict";',
+        'const __workspecModule = { exports: {} };',
+        'const __workspecExports = __workspecModule.exports;',
+        'const __workspecConsole = { log: () => {}, warn: () => {}, error: () => {} };',
+        'const __workspecRuntime = (function(require, process, Buffer, global, globalThis, module, exports, console) {',
+        '    "use strict";'
+    ];
+
+    lines.push(sourceCode);
+
+    lines.push('    return {');
+    lines.push('        exported: module.exports,');
+    lines.push('        functions: {');
+
+    if (captureFunctionNames.length > 0) {
+        captureFunctionNames.forEach((functionName, index) => {
+            const trailing = (index === captureFunctionNames.length - 1) ? '' : ',';
+            lines.push(`            ${JSON.stringify(functionName)}: (typeof ${functionName} === "function" ? ${functionName} : undefined)${trailing}`);
+        });
+    }
+
+    lines.push('        }');
+    lines.push('    };');
+    lines.push('})(undefined, undefined, undefined, undefined, undefined, __workspecModule, __workspecExports, __workspecConsole);');
+    lines.push('module.exports = {');
+    lines.push('    __workspec_exported: __workspecRuntime.exported,');
+    lines.push('    __workspec_functions: __workspecRuntime.functions');
+    lines.push('};');
+
+    return lines.join('\n');
+}
+
+function loadInstrumentedValidator(sourceCode, captureFunctionNames) {
+    const instrumentedSource = buildInstrumentedSource(sourceCode, captureFunctionNames);
+    const loader = new Function('module', 'exports', instrumentedSource); // eslint-disable-line no-new-func
+    const localModule = { exports: {} };
+    loader(localModule, localModule.exports);
+
+    const payload = isPlainObject(localModule.exports) ? localModule.exports : {};
+    const exported = payload.__workspec_exported;
+    const functionMap = isPlainObject(payload.__workspec_functions) ? payload.__workspec_functions : {};
+
+    return {
+        exported,
+        functionMap
     };
+}
 
+async function runAllowlistedValidation(functionMap, metrics, discoveredFunctions, helpers, problems) {
+    const allowedFunctions = new Set(discoveredFunctions);
     const thisArg = {
         simulation: helpers.simulation,
         addResult: helpers.addResult,
@@ -311,13 +343,9 @@ function runBrowserStyleValidation(sourceCode, metrics, helpers, customValidator
         _timeToMinutes: helpers._timeToMinutes
     };
 
-    const context = vm.createContext(sandbox);
-    const script = new vm.Script(sourceCode, { filename: customValidatorPath });
-    script.runInContext(context, { timeout: EXECUTION_TIMEOUT_MS });
-
     for (const metric of metrics) {
         const functionName = safeTrim(metric.functionName);
-        if (!FUNCTION_NAME_RE.test(functionName)) {
+        if (!FUNCTION_NAME_RE.test(functionName) || !ALLOWED_VALIDATE_FUNCTION_RE.test(functionName)) {
             problems.push(buildProblem(
                 metric.id || 'custom.validation.function_name',
                 'error',
@@ -328,40 +356,132 @@ function runBrowserStyleValidation(sourceCode, metrics, helpers, customValidator
             continue;
         }
 
-        context.__metric = {
+        if (!allowedFunctions.has(functionName)) {
+            problems.push(buildProblem(
+                metric.id || metricIdFromFunctionName(functionName),
+                'error',
+                'Disallowed Custom Validation Function',
+                `Function '${functionName}' is not in the allowlisted validate* entry points.`,
+                '/simulation',
+                { function: functionName, metric_id: metric.id || metricIdFromFunctionName(functionName) }
+            ));
+            continue;
+        }
+
+        const fn = functionMap[functionName];
+        const metricPayload = {
             id: metric.id || metricIdFromFunctionName(functionName),
             params: isPlainObject(metric.params) ? metric.params : {}
         };
-        context.__thisArg = thisArg;
-
-        const invocation = new vm.Script(
-            `(typeof ${functionName} === 'function') ? ${functionName}.call(__thisArg, __metric) : "__MISSING_FUNCTION__"`
-        );
 
-        const result = invocation.runInContext(context, { timeout: EXECUTION_TIMEOUT_MS });
-        if (result === '__MISSING_FUNCTION__') {
+        if (typeof fn !== 'function') {
             problems.push(buildProblem(
-                context.__metric.id,
+                metricPayload.id,
                 'error',
                 'Missing Custom Validation Function',
                 `Function '${functionName}' was not found in custom validation code.`,
                 '/simulation',
-                { function: functionName, metric_id: context.__metric.id }
+                { function: functionName, metric_id: metricPayload.id }
             ));
-        } else {
-            problems.push(...normalizeProblems(result, context.__metric.id));
+            continue;
         }
+
+        const result = await fn.call(thisArg, metricPayload);
+        problems.push(...normalizeProblems(result, metricPayload.id));
     }
 }
 
-async function runCustomValidation(documentValue, options = {}) {
-    const customValidatorPath = resolvePath(options.customValidatorPath || options.path || options.customPath);
-    const customCatalogPath = resolvePath(options.customCatalogPath || options.catalogPath);
+function withTrailingSeparator(value) {
+    return value.endsWith(path.sep) ? value : `${value}${path.sep}`;
+}
+
+function isPathInside(candidate, parent) {
+    if (candidate === parent) return true;
+    return candidate.startsWith(withTrailingSeparator(parent));
+}
+
+function hasRelativeTraversal(inputPath) {
+    const normalized = path.normalize(inputPath);
+    if (normalized === '..') return true;
+    return normalized.startsWith(`..${path.sep}`) || normalized.includes(`${path.sep}..${path.sep}`);
+}
+
+function resolveAndValidateFilePath(inputPath, label, allowedExtensions) {
+    const trimmed = safeTrim(inputPath);
+    if (!trimmed) return '';
+
+    if (trimmed.includes('\0')) {
+        throw new Error(`${label} contains unsupported null bytes.`);
+    }
+
+    const isAbsolute = path.isAbsolute(trimmed);
+    if (!isAbsolute && hasRelativeTraversal(trimmed)) {
+        throw new Error(`${label} contains path traversal segments: '${trimmed}'.`);
+    }
+
+    const resolvedPath = isAbsolute
+        ? path.resolve(trimmed)
+        : path.resolve(process.cwd(), trimmed);
+
+    let stats;
+    try {
+        stats = fs.statSync(resolvedPath);
+    } catch (error) {
+        throw new Error(`Failed to read ${label} (${resolvedPath}): ${error.message}`);
+    }
+
+    if (!stats.isFile()) {
+        throw new Error(`${label} must reference a file: ${resolvedPath}`);
+    }
+
+    let realPath;
+    try {
+        realPath = fs.realpathSync(resolvedPath);
+    } catch (error) {
+        throw new Error(`Failed to resolve ${label} (${resolvedPath}): ${error.message}`);
+    }
+
+    if (!isAbsolute) {
+        const cwdReal = fs.realpathSync(process.cwd());
+        if (!isPathInside(realPath, cwdReal)) {
+            throw new Error(`${label} resolves outside the current working directory: '${trimmed}'.`);
+        }
+    }
+
+    const extension = path.extname(realPath).toLowerCase();
+    if (!allowedExtensions.has(extension)) {
+        throw new Error(`${label} must use one of: ${[...allowedExtensions].join(', ')}.`);
+    }
+
+    return realPath;
+}
+
+function resolveExecutionOptions(options = {}) {
+    const customValidatorPath = resolveAndValidateFilePath(
+        options.customValidatorPath || options.path || options.customPath,
+        'Custom validator path',
+        VALIDATOR_EXTENSIONS
+    );
+
+    const customCatalogPath = resolveAndValidateFilePath(
+        options.customCatalogPath || options.catalogPath,
+        'Custom catalog path',
+        CATALOG_EXTENSIONS
+    );
 
     if (!customValidatorPath) {
         throw new Error('Missing custom validator path.');
     }
 
+    return {
+        customValidatorPath,
+        customCatalogPath
+    };
+}
+
+async function runCustomValidationInProcess(documentValue, options = {}) {
+    const { customValidatorPath, customCatalogPath } = resolveExecutionOptions(options);
+
     let sourceCode;
     try {
         sourceCode = fs.readFileSync(customValidatorPath, 'utf8');
@@ -369,30 +489,27 @@ async function runCustomValidation(documentValue, options = {}) {
         throw new Error(`Failed to read custom validator file (${customValidatorPath}): ${error.message}`);
     }
 
-    const problems = [];
-    const helpers = createHelpers(documentValue, problems);
+    const discoveredFunctions = discoverValidationFunctions(sourceCode);
+    const candidateCaptureNames = [...new Set(discoveredFunctions)];
 
-    let exported = null;
-    let exportedLoaded = false;
+    let instrumented;
     try {
-        const resolved = require.resolve(customValidatorPath);
-        delete require.cache[resolved];
-        exported = require(resolved);
-        exportedLoaded = true;
-    } catch (_error) {
-        exportedLoaded = false;
+        instrumented = loadInstrumentedValidator(sourceCode, candidateCaptureNames);
+    } catch (error) {
+        throw new Error(`Failed to evaluate custom validator (${customValidatorPath}): ${error.message}`);
     }
 
-    if (exportedLoaded) {
-        const handled = await runExportedValidation(exported, helpers, problems);
-        if (handled) {
-            return problems;
-        }
+    const problems = [];
+    const helpers = createHelpers(documentValue, problems);
+
+    const handled = await runExportedValidation(instrumented.exported, helpers, problems);
+    if (handled) {
+        return problems;
     }
 
     let metrics = loadMetricsCatalog(customValidatorPath, customCatalogPath);
     if (metrics.length === 0) {
-        metrics = discoverValidationFunctions(sourceCode).map((functionName) => ({
+        metrics = discoveredFunctions.map((functionName) => ({
             id: metricIdFromFunctionName(functionName),
             functionName,
             params: {}
@@ -407,7 +524,13 @@ async function runCustomValidation(documentValue, options = {}) {
     }
 
     try {
-        runBrowserStyleValidation(sourceCode, metrics, helpers, customValidatorPath, problems);
+        await runAllowlistedValidation(
+            instrumented.functionMap,
+            metrics,
+            discoveredFunctions,
+            helpers,
+            problems
+        );
     } catch (error) {
         throw new Error(`Custom validation execution failed (${customValidatorPath}): ${error.message}`);
     }
@@ -415,6 +538,121 @@ async function runCustomValidation(documentValue, options = {}) {
     return problems;
 }
 
+function runCustomValidationSubprocess(payload, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const workerPath = path.join(__dirname, 'custom-validation-worker.js');
+        const child = spawn(process.execPath, [workerPath], {
+            cwd: process.cwd(),
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: {
+                PATH: process.env.PATH || '',
+                NODE_ENV: 'production',
+                NODE_OPTIONS: ''
+            }
+        });
+
+        let stdout = '';
+        let stderr = '';
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+
+        function fail(error) {
+            if (settled) return;
+            settled = true;
+            reject(error);
+        }
+
+        const timer = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            child.kill('SIGKILL');
+            reject(new Error(`Custom validation timed out after ${timeoutMs}ms.`));
+        }, timeoutMs + SUBPROCESS_GRACE_MS);
+
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            fail(new Error(`Failed to start custom validation worker: ${error.message}`));
+        });
+
+        child.stdout.on('data', (chunk) => {
+            if (settled) return;
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > MAX_SUBPROCESS_OUTPUT_BYTES) {
+                child.kill('SIGKILL');
+                clearTimeout(timer);
+                fail(new Error('Custom validation worker output exceeded the allowed limit.'));
+                return;
+            }
+            stdout += chunk.toString('utf8');
+        });
+
+        child.stderr.on('data', (chunk) => {
+            if (settled) return;
+            stderrBytes += chunk.length;
+            if (stderrBytes > MAX_SUBPROCESS_OUTPUT_BYTES) {
+                child.kill('SIGKILL');
+                clearTimeout(timer);
+                fail(new Error('Custom validation worker error output exceeded the allowed limit.'));
+                return;
+            }
+            stderr += chunk.toString('utf8');
+        });
+
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (settled) return;
+
+            if (signal && signal !== 'SIGTERM') {
+                fail(new Error(`Custom validation worker exited with signal ${signal}.`));
+                return;
+            }
+
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout || '{}');
+            } catch (error) {
+                const details = stderr.trim() || `Invalid worker output: ${error.message}`;
+                fail(new Error(`Custom validation worker returned unreadable output. ${details}`));
+                return;
+            }
+
+            if (code !== 0 || !parsed.ok) {
+                const message = safeTrim(parsed.error) || safeTrim(stderr) || `Worker exited with code ${code}.`;
+                fail(new Error(message));
+                return;
+            }
+
+            if (!Array.isArray(parsed.problems)) {
+                fail(new Error('Custom validation worker returned an invalid payload.'));
+                return;
+            }
+
+            settled = true;
+            resolve(parsed.problems);
+        });
+
+        child.stdin.on('error', (error) => {
+            clearTimeout(timer);
+            fail(new Error(`Failed to send input to custom validation worker: ${error.message}`));
+        });
+
+        child.stdin.end(JSON.stringify(payload));
+    });
+}
+
+async function runCustomValidation(documentValue, options = {}) {
+    const executionOptions = resolveExecutionOptions(options);
+    return runCustomValidationSubprocess(
+        {
+            documentValue,
+            options: executionOptions
+        },
+        EXECUTION_TIMEOUT_MS
+    );
+}
+
 module.exports = {
-    runCustomValidation
+    runCustomValidation,
+    runCustomValidationInProcess
 };

package/custom-validation-worker.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runCustomValidationInProcess } = require('./custom-validation-runner.js');
+
+const MAX_INPUT_BYTES = 1024 * 1024;
+
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let totalBytes = 0;
+        let data = '';
+
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > MAX_INPUT_BYTES) {
+                reject(new Error('Custom validation payload exceeded the allowed size.'));
+                return;
+            }
+            data += chunk;
+        });
+
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+
+async function main() {
+    try {
+        const raw = await readStdin();
+        const payload = JSON.parse(raw || '{}');
+
+        const documentValue = payload?.documentValue;
+        const options = payload?.options || {};
+
+        const problems = await runCustomValidationInProcess(documentValue, options);
+        process.stdout.write(JSON.stringify({ ok: true, problems }));
+        process.exitCode = 0;
+    } catch (error) {
+        process.stdout.write(JSON.stringify({
+            ok: false,
+            error: (error && error.message) ? error.message : 'Unknown custom validation worker error.'
+        }));
+        process.exitCode = 1;
+    }
+}
+
+main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "workspec",
   "private": false,
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "WorkSpec v1.1.0 validator and CLI (validate/migrate/format + custom validation).",
   "license": "AGPL-3.0",
   "main": "index.js",
@@ -11,12 +11,14 @@
   "scripts": {
     "check:sync": "node scripts/check-sync.js",
     "sync:web": "node scripts/sync-web-assets.js",
-    "test": "node scripts/self-test.js"
+    "test:integration": "node scripts/sync-web-assets.js && node scripts/test-playground-integration.js",
+    "test": "node scripts/self-test.js && npm run test:integration"
   },
   "files": [
     "bin/",
     "index.js",
     "custom-validation-runner.js",
+    "custom-validation-worker.js",
     "workspec-validator.js",
     "workspec-migrate-v1-to-v2.js",
     "v2.0.schema.json",