commandmate 0.11.4 → 0.12.0

package/dist/server/src/lib/skills/package-validator.js

@@ -0,0 +1,451 @@
+"use strict";
+/**
+ * Full package/manifest reconciliation and safe materialization (Issue #1230)
+ *
+ * Second half of the inspect-then-materialize boundary. `package-reader` decides
+ * whether the bytes are an archive we are willing to look at; this module
+ * decides whether the archive is *the package the manifest describes*, and only
+ * then writes it into an isolated staging directory.
+ *
+ * Reconciliation is exact in both directions. Every regular payload file except
+ * the manifest itself must be declared, every declaration must be present, and
+ * each one must agree on size, digest, kind, executable bit and script status.
+ * A partial match is a rejection: "mostly the manifest the user reviewed" is
+ * how an undeclared script gets installed.
+ *
+ * Nothing in the package is executed, at any point, by any code path here.
+ *
+ * @module lib/skills/package-validator
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_SCRIPT_EXTENSIONS = exports.SKILL_STAGING_ENTRY_PREFIX = exports.SKILL_STAGED_EXECUTABLE_MODE = exports.SKILL_STAGED_FILE_MODE = exports.SKILL_STAGING_DIR_MODE = void 0;
+exports.isSkillScriptPayload = isSkillScriptPayload;
+exports.deriveSkillFileKind = deriveSkillFileKind;
+exports.validateSkillPackage = validateSkillPackage;
+exports.inspectSkillPackage = inspectSkillPackage;
+exports.materializeSkillPackage = materializeSkillPackage;
+exports.cleanupSkillStagingRoot = cleanupSkillStagingRoot;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const system_directories_1 = require("../../config/system-directories");
+const skills_1 = require("../../lib/skills");
+const integrity_1 = require("../../lib/skills/integrity");
+const package_reader_1 = require("../../lib/skills/package-reader");
+const safe_yaml_1 = require("../../lib/skills/safe-yaml");
+// =============================================================================
+// Staging policy
+// =============================================================================
+/** Staging directories are private to the service account. */
+exports.SKILL_STAGING_DIR_MODE = 0o700;
+/** Non-executable payload files land read/write for the owner only. */
+exports.SKILL_STAGED_FILE_MODE = 0o600;
+/** Declared executables additionally get the owner execute bit. Nothing else. */
+exports.SKILL_STAGED_EXECUTABLE_MODE = 0o700;
+/** Prefix of a staging directory, used to recognize orphans after a restart. */
+exports.SKILL_STAGING_ENTRY_PREFIX = 'pkg-';
+const STAGING_ENTRY_PATTERN = /^pkg-[0-9a-f]{32}$/;
+/** `O_NOFOLLOW` is POSIX-only; on platforms without it the flag is a no-op. */
+const O_NOFOLLOW = fs_1.constants.O_NOFOLLOW ?? 0;
+// =============================================================================
+// Script classification
+// =============================================================================
+/**
+ * Extensions treated as scripts regardless of content.
+ *
+ * Classification is deliberately over-broad: a file wrongly called a script
+ * only forces the publisher to declare it, while a missed one would install an
+ * interpreted payload the user never saw listed.
+ */
+exports.SKILL_SCRIPT_EXTENSIONS = [
+    '.bash',
+    '.bat',
+    '.cjs',
+    '.cmd',
+    '.fish',
+    '.js',
+    '.lua',
+    '.mjs',
+    '.php',
+    '.pl',
+    '.ps1',
+    '.py',
+    '.rb',
+    '.sh',
+    '.ts',
+    '.zsh',
+];
+const INSTRUCTION_EXTENSIONS = ['.md', '.markdown', '.rst', '.txt'];
+function extensionOf(filePath) {
+    const base = filePath.slice(filePath.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    return dot <= 0 ? '' : base.slice(dot).toLowerCase();
+}
+/** Whether a payload file is an interpreted script, by extension or shebang. */
+function isSkillScriptPayload(filePath, bytes) {
+    if (exports.SKILL_SCRIPT_EXTENSIONS.includes(extensionOf(filePath)))
+        return true;
+    return bytes.length >= 2 && bytes[0] === 0x23 && bytes[1] === 0x21;
+}
+/** Role CommandMate derives for a payload file, independent of the declaration. */
+function deriveSkillFileKind(filePath, bytes) {
+    if (filePath === skills_1.SKILL_MD_FILENAME)
+        return 'skill_md';
+    if (isSkillScriptPayload(filePath, bytes))
+        return 'script';
+    return INSTRUCTION_EXTENSIONS.includes(extensionOf(filePath)) ? 'instruction' : 'asset';
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function fail(code, detail) {
+    throw new package_reader_1.SkillPackageError(code, detail);
+}
+function findFile(table, filePath) {
+    return table.files.find((file) => file.path === filePath);
+}
+// =============================================================================
+// Manifest reconciliation
+// =============================================================================
+function readManifest(table) {
+    const manifestEntry = findFile(table, skills_1.SKILL_MANIFEST_FILENAME);
+    if (!manifestEntry)
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISSING, { reason: 'absent' });
+    for (const file of table.files) {
+        if (file.path !== skills_1.SKILL_MANIFEST_FILENAME && file.path.endsWith(`/${skills_1.SKILL_MANIFEST_FILENAME}`)) {
+            fail(package_reader_1.SkillPackageErrorCode.LAYOUT_INVALID, {
+                reason: 'nested-manifest',
+                entry: (0, package_reader_1.encodeEntryPathForError)(file.path),
+            });
+        }
+    }
+    let parsed;
+    try {
+        parsed = (0, safe_yaml_1.parseSkillYaml)(manifestEntry.bytes);
+    }
+    catch (error) {
+        if ((0, safe_yaml_1.isSkillYamlError)(error)) {
+            fail(package_reader_1.SkillPackageErrorCode.MANIFEST_INVALID, { reason: error.code });
+        }
+        throw error;
+    }
+    const result = (0, skills_1.validateSkillManifest)(parsed);
+    if (!result.ok) {
+        const first = result.errors[0];
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_INVALID, { reason: first.code, field: first.path });
+    }
+    return result.value;
+}
+function assertRequiredEntries(table) {
+    for (const required of skills_1.REQUIRED_PACKAGE_ENTRIES) {
+        if (!findFile(table, required)) {
+            fail(package_reader_1.SkillPackageErrorCode.LAYOUT_INVALID, {
+                reason: 'missing-required-entry',
+                entry: required,
+            });
+        }
+    }
+}
+function assertSkillMdConsistency(table, manifest) {
+    const skillMd = findFile(table, skills_1.SKILL_MD_FILENAME);
+    if (!skillMd)
+        fail(package_reader_1.SkillPackageErrorCode.SKILL_MD_INVALID, { reason: 'absent' });
+    let frontmatter;
+    try {
+        frontmatter = (0, safe_yaml_1.parseSkillFrontmatter)(Buffer.from(skillMd.bytes).toString('utf8'));
+    }
+    catch (error) {
+        if ((0, safe_yaml_1.isSkillYamlError)(error)) {
+            fail(package_reader_1.SkillPackageErrorCode.SKILL_MD_INVALID, { reason: error.code });
+        }
+        throw error;
+    }
+    if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+        fail(package_reader_1.SkillPackageErrorCode.SKILL_MD_INVALID, { reason: 'frontmatter-missing' });
+    }
+    const name = frontmatter['name'];
+    if (typeof name !== 'string') {
+        fail(package_reader_1.SkillPackageErrorCode.SKILL_MD_INVALID, { reason: 'frontmatter-name-missing' });
+    }
+    const consistency = (0, skills_1.validateSkillIdentityConsistency)({
+        directoryName: manifest.id,
+        skillMdName: name,
+        manifestId: manifest.id,
+        manifestName: manifest.name,
+    });
+    if (!consistency.ok) {
+        fail(package_reader_1.SkillPackageErrorCode.SKILL_MD_INVALID, { reason: consistency.errors[0].code });
+    }
+}
+/**
+ * Both directions of the file-set comparison.
+ *
+ * Self-declaration and duplicate declarations are already refused by
+ * `validateSkillManifest` (#1228); what is left for this step is the package
+ * the manifest is being compared against.
+ */
+function assertFileSetMatches(table, manifest) {
+    const result = (0, skills_1.validateManifestFileSet)(manifest, table.files.map((file) => file.path));
+    if (!result.ok) {
+        const first = result.errors[0];
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, {
+            reason: first.message,
+            entry: (0, package_reader_1.encodeEntryPathForError)(String(first.detail?.['path'] ?? '')),
+        });
+    }
+}
+/** Cross-check one payload file against its declaration on every axis. */
+function assertDeclarationMatches(entry, manifest) {
+    const declared = manifest.files.find((file) => file.path === entry.path);
+    if (!declared) {
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, {
+            reason: 'undeclared-file',
+            entry: (0, package_reader_1.encodeEntryPathForError)(entry.path),
+        });
+    }
+    const detail = { entry: (0, package_reader_1.encodeEntryPathForError)(entry.path) };
+    if (declared.size !== entry.size)
+        fail(package_reader_1.SkillPackageErrorCode.SIZE_MISMATCH, detail);
+    if (!(0, integrity_1.digestMatches)(declared.sha256, entry.sha256)) {
+        fail(package_reader_1.SkillPackageErrorCode.DIGEST_MISMATCH, detail);
+    }
+    const derivedKind = deriveSkillFileKind(entry.path, entry.bytes);
+    const isScript = isSkillScriptPayload(entry.path, entry.bytes);
+    if (isScript && (!declared.script || declared.kind !== 'script')) {
+        fail(package_reader_1.SkillPackageErrorCode.UNDECLARED_SCRIPT, detail);
+    }
+    if (declared.kind === 'script' && !declared.script) {
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, { ...detail, reason: 'kind-script-not-declared' });
+    }
+    if ((derivedKind === 'skill_md') !== (declared.kind === 'skill_md')) {
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, { ...detail, reason: 'kind-mismatch' });
+    }
+    if (entry.executable && !declared.executable) {
+        fail(package_reader_1.SkillPackageErrorCode.UNDECLARED_EXECUTABLE, detail);
+    }
+    if (!entry.executable && declared.executable) {
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, { ...detail, reason: 'executable-not-present' });
+    }
+}
+// =============================================================================
+// Validation
+// =============================================================================
+/**
+ * Reconcile a parsed package with its manifest and the Catalog coordinates.
+ *
+ * @param table Entry table from `readSkillPackage`
+ * @param options Coordinates the Catalog published this version under
+ * @returns An immutable snapshot, or throws before any consumer can see it
+ * @throws SkillPackageError for every rejection
+ */
+function validateSkillPackage(table, options) {
+    assertRequiredEntries(table);
+    const manifest = readManifest(table);
+    if (manifest.id !== options.skillId) {
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, { reason: 'id' });
+    }
+    if (manifest.version !== options.version) {
+        fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, { reason: 'version' });
+    }
+    assertSkillMdConsistency(table, manifest);
+    assertFileSetMatches(table, manifest);
+    for (const entry of table.files) {
+        if (entry.path === skills_1.SKILL_MANIFEST_FILENAME)
+            continue;
+        assertDeclarationMatches(entry, manifest);
+    }
+    const executablePaths = manifest.files.filter((f) => f.executable).map((f) => f.path).sort();
+    const scriptPaths = manifest.files.filter((f) => f.script).map((f) => f.path).sort();
+    const inspection = {
+        executable_paths: executablePaths,
+        script_paths: scriptPaths,
+        network_hosts: [...manifest.requirements.network_hosts],
+        declared_permissions: [...manifest.declared_permissions],
+    };
+    const computedRisk = (0, skills_1.computeSkillRisk)(inspection);
+    const byPath = new Map(table.files.map((file) => [file.path, file.bytes]));
+    const files = table.files
+        .map((file) => ({
+        path: file.path,
+        sha256: file.sha256,
+        size: file.size,
+        executable: file.executable,
+    }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return Object.freeze({
+        skillId: options.skillId,
+        version: options.version,
+        manifest,
+        files: Object.freeze(files),
+        directories: Object.freeze([...table.directories].sort()),
+        inspection: Object.freeze(inspection),
+        declaredRisk: manifest.declared_risk,
+        computedRisk,
+        effectiveRisk: (0, skills_1.resolveEffectiveSkillRisk)(manifest.declared_risk, computedRisk),
+        readFile(filePath) {
+            const bytes = byPath.get(filePath);
+            if (!bytes) {
+                fail(package_reader_1.SkillPackageErrorCode.MANIFEST_MISMATCH, {
+                    reason: 'unknown-file',
+                    entry: (0, package_reader_1.encodeEntryPathForError)(filePath),
+                });
+            }
+            return new Uint8Array(bytes);
+        },
+    });
+}
+/**
+ * Read and reconcile an artifact in one step.
+ *
+ * The two halves are separately testable but must always run together: a table
+ * that was read but not reconciled is not a package, and nothing downstream
+ * should be able to obtain one.
+ *
+ * @throws SkillPackageError for every rejection
+ */
+function inspectSkillPackage(artifact, options) {
+    return validateSkillPackage((0, package_reader_1.readSkillPackage)(artifact, options), options);
+}
+// =============================================================================
+// Materialization
+// =============================================================================
+function assertNotAborted(signal) {
+    if (signal?.aborted)
+        fail(package_reader_1.SkillPackageErrorCode.ABORTED);
+}
+/** Create a directory that must not already exist and must not be a symlink. */
+function createDirectory(target) {
+    try {
+        (0, fs_1.mkdirSync)(target, { mode: exports.SKILL_STAGING_DIR_MODE });
+    }
+    catch {
+        fail(package_reader_1.SkillPackageErrorCode.STAGING_IO, { reason: 'mkdir' });
+    }
+    const stats = (0, fs_1.lstatSync)(target);
+    if (!stats.isDirectory())
+        fail(package_reader_1.SkillPackageErrorCode.STAGING_IO, { reason: 'not-a-directory' });
+}
+/**
+ * Write one payload file.
+ *
+ * `O_CREAT|O_EXCL|O_NOFOLLOW` means the write either creates the file itself or
+ * fails: a symlink or an existing file planted between the directory scan and
+ * this call cannot be written through. The digest is re-read afterwards, so a
+ * file that changed underneath us never reaches the inventory.
+ */
+function writePayloadFile(target, snapshot, file) {
+    const bytes = snapshot.readFile(file.path);
+    const declared = snapshot.manifest.files.find((entry) => entry.path === file.path);
+    const mode = declared?.executable ? exports.SKILL_STAGED_EXECUTABLE_MODE : exports.SKILL_STAGED_FILE_MODE;
+    let fd;
+    try {
+        fd = (0, fs_1.openSync)(target, fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | O_NOFOLLOW, mode);
+    }
+    catch {
+        fail(package_reader_1.SkillPackageErrorCode.STAGING_IO, { reason: 'open' });
+    }
+    try {
+        let written = 0;
+        while (written < bytes.byteLength) {
+            written += (0, fs_1.writeSync)(fd, bytes, written, bytes.byteLength - written);
+        }
+    }
+    catch {
+        (0, fs_1.closeSync)(fd);
+        fail(package_reader_1.SkillPackageErrorCode.STAGING_IO, { reason: 'write' });
+    }
+    (0, fs_1.closeSync)(fd);
+    const stats = (0, fs_1.lstatSync)(target);
+    if (!stats.isFile() || stats.nlink !== 1 || stats.size !== bytes.byteLength) {
+        fail(package_reader_1.SkillPackageErrorCode.STAGING_IO, { reason: 'verify-stat' });
+    }
+    if (!(0, integrity_1.digestMatches)((0, integrity_1.computeSha256Hex)((0, fs_1.readFileSync)(target)), file.sha256)) {
+        fail(package_reader_1.SkillPackageErrorCode.DIGEST_MISMATCH, { reason: 'staged-readback' });
+    }
+}
+/**
+ * Write a validated package into a fresh, private staging directory.
+ *
+ * Nothing outside the new directory is touched and nothing from the archive
+ * (owner, timestamps, mode) is applied: directories and files get fixed modes,
+ * and only files the manifest declared executable get an execute bit.
+ *
+ * On any failure — including an abort — the whole staging directory is removed
+ * before the error propagates, so no consumer can ever observe a partial
+ * package.
+ *
+ * @throws SkillPackageError with `STAGING_IO`, `ABORTED` or `DIGEST_MISMATCH`
+ */
+function materializeSkillPackage(snapshot, options) {
+    const root = path_1.default.resolve(options.stagingRoot);
+    if ((0, system_directories_1.isSystemDirectory)(root))
+        fail(package_reader_1.SkillPackageErrorCode.STAGING_IO, { reason: 'system-directory' });
+    try {
+        (0, fs_1.mkdirSync)(root, { recursive: true, mode: exports.SKILL_STAGING_DIR_MODE });
+    }
+    catch {
+        fail(package_reader_1.SkillPackageErrorCode.STAGING_IO, { reason: 'mkdir-root' });
+    }
+    const stagingDir = path_1.default.join(root, `${exports.SKILL_STAGING_ENTRY_PREFIX}${(0, crypto_1.randomBytes)(16).toString('hex')}`);
+    createDirectory(stagingDir);
+    try {
+        assertNotAborted(options.signal);
+        const directories = new Set(snapshot.directories);
+        for (const file of snapshot.files) {
+            const parents = file.path.split('/').slice(0, -1);
+            let walked = '';
+            for (const segment of parents) {
+                walked = walked === '' ? segment : `${walked}/${segment}`;
+                directories.add(walked);
+            }
+        }
+        for (const directory of [...directories].sort()) {
+            createDirectory(path_1.default.join(stagingDir, directory));
+        }
+        for (const file of snapshot.files) {
+            assertNotAborted(options.signal);
+            writePayloadFile(path_1.default.join(stagingDir, file.path), snapshot, file);
+        }
+    }
+    catch (error) {
+        (0, fs_1.rmSync)(stagingDir, { recursive: true, force: true });
+        throw error;
+    }
+    let disposed = false;
+    return {
+        skillId: snapshot.skillId,
+        version: snapshot.version,
+        stagingDir,
+        inventory: snapshot.files,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            (0, fs_1.rmSync)(stagingDir, { recursive: true, force: true });
+        },
+    };
+}
+/**
+ * Remove staging directories left behind by a crashed or killed process.
+ *
+ * Only entries this module creates are removed, so pointing it at a directory
+ * that holds anything else cannot destroy that content.
+ *
+ * @returns Number of staging directories removed
+ */
+function cleanupSkillStagingRoot(stagingRoot) {
+    const root = path_1.default.resolve(stagingRoot);
+    if ((0, system_directories_1.isSystemDirectory)(root) || !(0, fs_1.existsSync)(root))
+        return 0;
+    let removed = 0;
+    for (const entry of (0, fs_1.readdirSync)(root)) {
+        if (!STAGING_ENTRY_PATTERN.test(entry))
+            continue;
+        (0, fs_1.rmSync)(path_1.default.join(root, entry), { recursive: true, force: true });
+        removed += 1;
+    }
+    return removed;
+}