commandmate 0.11.3 → 0.12.0

package/dist/server/src/lib/skills/safe-yaml.js

@@ -0,0 +1,593 @@
+"use strict";
+/**
+ * Restricted YAML reader for Skill manifests (Issue #1230)
+ *
+ * `SKILL_YAML_SAFE_PROFILE` (#1228) fixed the limits a manifest parser must
+ * enforce but deliberately left the implementation open. This module closes it
+ * with a parser for a *subset* of YAML rather than a configured general-purpose
+ * one, for two reasons:
+ *
+ * - No dependency in the tree can enforce the profile. `js-yaml` (reachable
+ *   only transitively, through `gray-matter`) has no depth, node-count or
+ *   scalar-size bound and resolves anchors and merge keys by default, which is
+ *   exactly the parser-bomb surface the profile exists to remove.
+ * - A manifest is a closed document: schema_version 1 has no field that needs
+ *   anchors, tags, flow collections or multiple documents. Everything outside
+ *   the subset is therefore a rejection, not a parse.
+ *
+ * The subset is: one document, block mappings, block sequences, plain and
+ * quoted scalars, literal/folded block scalars, empty flow collections and
+ * comments. Anchors, aliases, merge keys, tags, non-empty flow collections,
+ * complex keys and additional documents are refused with their own code so a
+ * caller can tell "malicious" from "malformed".
+ *
+ * Parsed mappings have a null prototype: `__proto__` is rejected by the profile
+ * *and* is inert if that check is ever weakened.
+ *
+ * @module lib/skills/safe-yaml
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillYamlError = exports.SkillYamlErrorCode = void 0;
+exports.isSkillYamlError = isSkillYamlError;
+exports.parseSkillYaml = parseSkillYaml;
+exports.parseSkillFrontmatter = parseSkillFrontmatter;
+const skills_1 = require("../../lib/skills");
+// =============================================================================
+// Error vocabulary
+// =============================================================================
+/** Stable, client-safe reason codes for a rejected YAML document. */
+exports.SkillYamlErrorCode = {
+    /** Document is larger than the profile's byte budget. */
+    BYTES_LIMIT: 'SKILL_YAML_BYTES_LIMIT',
+    /** Nesting is deeper than the profile allows. */
+    DEPTH_LIMIT: 'SKILL_YAML_DEPTH_LIMIT',
+    /** Document has more nodes than the profile allows. */
+    NODE_LIMIT: 'SKILL_YAML_NODE_LIMIT',
+    /** A single scalar is longer than the profile allows. */
+    SCALAR_LIMIT: 'SKILL_YAML_SCALAR_LIMIT',
+    /** An anchor (`&`) or alias (`*`) was used. */
+    ALIAS_FORBIDDEN: 'SKILL_YAML_ALIAS_FORBIDDEN',
+    /** A merge key (`<<`) was used. */
+    MERGE_KEY_FORBIDDEN: 'SKILL_YAML_MERGE_KEY_FORBIDDEN',
+    /** An explicit tag (`!`/`!!`) was used. */
+    TAG_FORBIDDEN: 'SKILL_YAML_TAG_FORBIDDEN',
+    /** The same key appears twice in one mapping. */
+    DUPLICATE_KEY: 'SKILL_YAML_DUPLICATE_KEY',
+    /** A key on the profile's forbidden list (prototype pollution) was used. */
+    FORBIDDEN_KEY: 'SKILL_YAML_FORBIDDEN_KEY',
+    /** The stream carries more than one document. */
+    MULTIPLE_DOCUMENTS: 'SKILL_YAML_MULTIPLE_DOCUMENTS',
+    /** Bytes are not valid UTF-8, or carry a BOM or a control character. */
+    ENCODING: 'SKILL_YAML_ENCODING',
+    /** A construct outside the supported subset was used. */
+    UNSUPPORTED: 'SKILL_YAML_UNSUPPORTED',
+    /** The document does not parse as the supported subset. */
+    SYNTAX: 'SKILL_YAML_SYNTAX',
+};
+const MESSAGES = {
+    [exports.SkillYamlErrorCode.BYTES_LIMIT]: 'YAML document exceeds the size limit',
+    [exports.SkillYamlErrorCode.DEPTH_LIMIT]: 'YAML document is nested too deeply',
+    [exports.SkillYamlErrorCode.NODE_LIMIT]: 'YAML document has too many nodes',
+    [exports.SkillYamlErrorCode.SCALAR_LIMIT]: 'YAML scalar exceeds the length limit',
+    [exports.SkillYamlErrorCode.ALIAS_FORBIDDEN]: 'YAML anchors and aliases are not accepted',
+    [exports.SkillYamlErrorCode.MERGE_KEY_FORBIDDEN]: 'YAML merge keys are not accepted',
+    [exports.SkillYamlErrorCode.TAG_FORBIDDEN]: 'YAML tags are not accepted',
+    [exports.SkillYamlErrorCode.DUPLICATE_KEY]: 'YAML mapping declares the same key twice',
+    [exports.SkillYamlErrorCode.FORBIDDEN_KEY]: 'YAML mapping uses a forbidden key',
+    [exports.SkillYamlErrorCode.MULTIPLE_DOCUMENTS]: 'YAML stream carries more than one document',
+    [exports.SkillYamlErrorCode.ENCODING]: 'YAML document is not valid UTF-8 text',
+    [exports.SkillYamlErrorCode.UNSUPPORTED]: 'YAML document uses an unsupported construct',
+    [exports.SkillYamlErrorCode.SYNTAX]: 'YAML document could not be parsed',
+};
+/**
+ * A rejected YAML document.
+ *
+ * Carries a line number but never the offending text: a manifest can embed
+ * anything, and echoing it back would turn the parser into a reflection gadget.
+ */
+class SkillYamlError extends Error {
+    code;
+    /** 1-based line the rejection was raised at, when known. */
+    line;
+    constructor(code, line) {
+        super(MESSAGES[code]);
+        this.name = 'SkillYamlError';
+        this.code = code;
+        if (line !== undefined)
+            this.line = line;
+    }
+}
+exports.SkillYamlError = SkillYamlError;
+/** Narrow an unknown thrown value to a {@link SkillYamlError}. */
+function isSkillYamlError(value) {
+    return value instanceof SkillYamlError;
+}
+const KEY_HEAD = /^(?:"(?:[^"\\]|\\.)*"|'(?:[^']|'')*'|[A-Za-z_][A-Za-z0-9_.-]*)[ \t]*:(?:[ \t]|$)/;
+function decodeUtf8(input, maxBytes) {
+    const byteLength = typeof input === 'string' ? Buffer.byteLength(input, 'utf8') : input.byteLength;
+    if (byteLength > maxBytes)
+        throw new SkillYamlError(exports.SkillYamlErrorCode.BYTES_LIMIT);
+    if (typeof input === 'string')
+        return input;
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(input);
+    }
+    catch {
+        throw new SkillYamlError(exports.SkillYamlErrorCode.ENCODING);
+    }
+}
+/** Split into lines, rejecting anything that is not plain UTF-8 text. */
+function toLines(text) {
+    if (text.includes('\uFEFF'))
+        throw new SkillYamlError(exports.SkillYamlErrorCode.ENCODING);
+    const normalized = text.replace(/\r\n/g, '\n');
+    if (normalized.includes('\r'))
+        throw new SkillYamlError(exports.SkillYamlErrorCode.ENCODING);
+    const lines = [];
+    const rawLines = normalized.split('\n');
+    for (let i = 0; i < rawLines.length; i++) {
+        const raw = rawLines[i];
+        const number = i + 1;
+        for (let j = 0; j < raw.length; j++) {
+            const code = raw.charCodeAt(j);
+            if ((code < 0x20 && code !== 0x09) || code === 0x7f) {
+                throw new SkillYamlError(exports.SkillYamlErrorCode.ENCODING, number);
+            }
+        }
+        let indent = 0;
+        while (indent < raw.length && raw[indent] === ' ')
+            indent++;
+        if (raw[indent] === '\t')
+            throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, number);
+        const content = raw.slice(indent);
+        lines.push({
+            number,
+            raw,
+            indent,
+            content,
+            significant: content.length > 0 && !content.startsWith('#'),
+        });
+    }
+    return lines;
+}
+/**
+ * Drop a trailing comment, honouring quotes.
+ *
+ * `summary: "a # b"` keeps its hash; `summary: a # b` does not.
+ */
+function stripComment(text) {
+    let quote = null;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quote === '"') {
+            if (ch === '\\')
+                i++;
+            else if (ch === '"')
+                quote = null;
+        }
+        else if (quote === "'") {
+            if (ch === "'")
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === '#' && (i === 0 || text[i - 1] === ' ' || text[i - 1] === '\t')) {
+            return text.slice(0, i);
+        }
+    }
+    return text;
+}
+// =============================================================================
+// Parser
+// =============================================================================
+class Parser {
+    lines;
+    profile;
+    cursor = 0;
+    nodes = 0;
+    documentEnded = false;
+    documentStarted = false;
+    constructor(lines, profile) {
+        this.lines = lines;
+        this.profile = profile;
+    }
+    parseDocument() {
+        const first = this.peek();
+        if (!first)
+            return null;
+        if (first.indent !== 0)
+            throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, first.number);
+        const value = this.parseNode(0, 1);
+        this.skipToSignificant();
+        const trailing = this.peek();
+        if (trailing)
+            throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, trailing.number);
+        return value;
+    }
+    // ---------------------------------------------------------------------------
+    // Cursor
+    // ---------------------------------------------------------------------------
+    skipToSignificant() {
+        while (this.cursor < this.lines.length) {
+            const line = this.lines[this.cursor];
+            if (!line.significant) {
+                this.cursor++;
+                continue;
+            }
+            const trimmed = line.content.trim();
+            if (trimmed === '...') {
+                this.documentEnded = true;
+                this.cursor++;
+                continue;
+            }
+            if (trimmed === '---') {
+                // Only the marker that opens the stream is a document start; a later one
+                // begins a second document, which this parser never accepts.
+                if (this.documentStarted) {
+                    throw new SkillYamlError(exports.SkillYamlErrorCode.MULTIPLE_DOCUMENTS, line.number);
+                }
+                this.documentStarted = true;
+                this.cursor++;
+                continue;
+            }
+            if (this.documentEnded) {
+                throw new SkillYamlError(exports.SkillYamlErrorCode.MULTIPLE_DOCUMENTS, line.number);
+            }
+            this.documentStarted = true;
+            return;
+        }
+    }
+    peek() {
+        this.skipToSignificant();
+        return this.cursor < this.lines.length ? this.lines[this.cursor] : null;
+    }
+    countNode(line) {
+        this.nodes++;
+        if (this.nodes > this.profile.maxNodes) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.NODE_LIMIT, line.number);
+        }
+    }
+    checkDepth(depth, line) {
+        if (depth > this.profile.maxDepth) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.DEPTH_LIMIT, line.number);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Collections
+    // ---------------------------------------------------------------------------
+    parseNode(indent, depth) {
+        const line = this.peek();
+        if (!line)
+            return null;
+        this.checkDepth(depth, line);
+        return this.isSequenceEntry(line.content)
+            ? this.parseSequence(indent, depth)
+            : this.parseMapping(indent, depth);
+    }
+    isSequenceEntry(content) {
+        return content === '-' || content.startsWith('- ');
+    }
+    parseMapping(indent, depth) {
+        const result = Object.create(null);
+        const seen = new Set();
+        for (;;) {
+            const line = this.peek();
+            if (!line || line.indent < indent)
+                break;
+            if (line.indent > indent)
+                throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+            if (this.isSequenceEntry(line.content)) {
+                throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+            }
+            this.countNode(line);
+            const key = this.readKey(line);
+            if (seen.has(key) && !this.profile.allowDuplicateKeys) {
+                throw new SkillYamlError(exports.SkillYamlErrorCode.DUPLICATE_KEY, line.number);
+            }
+            seen.add(key);
+            const colon = line.content.indexOf(':', this.keyTokenLength(line.content));
+            const rest = stripComment(line.content.slice(colon + 1)).trim();
+            this.cursor++;
+            result[key] = this.parseValue(rest, indent, depth, line);
+        }
+        return result;
+    }
+    parseSequence(indent, depth) {
+        const result = [];
+        for (;;) {
+            const line = this.peek();
+            if (!line || line.indent < indent)
+                break;
+            if (line.indent > indent)
+                throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+            if (!this.isSequenceEntry(line.content))
+                break;
+            this.countNode(line);
+            const rest = line.content === '-' ? '' : line.content.slice(2);
+            const offset = line.content.length - rest.length;
+            const trimmedRest = stripComment(rest).trim();
+            if (trimmedRest === '') {
+                this.cursor++;
+                result.push(this.parseIndentedValue(indent, depth + 1, line));
+                continue;
+            }
+            if (this.isSequenceEntry(trimmedRest)) {
+                throw new SkillYamlError(exports.SkillYamlErrorCode.UNSUPPORTED, line.number);
+            }
+            if (KEY_HEAD.test(rest.trimStart())) {
+                // Re-anchor `- key: value` as a mapping line at the item's own indent so
+                // its sibling keys on following lines line up with it.
+                const itemIndent = indent + offset + (rest.length - rest.trimStart().length);
+                line.indent = itemIndent;
+                line.content = rest.trimStart();
+                this.checkDepth(depth + 1, line);
+                result.push(this.parseMapping(itemIndent, depth + 1));
+                continue;
+            }
+            this.cursor++;
+            this.countNode(line);
+            result.push(this.parseScalar(trimmedRest, line));
+        }
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // Keys and values
+    // ---------------------------------------------------------------------------
+    keyTokenLength(content) {
+        if (content.startsWith('"') || content.startsWith("'")) {
+            const quote = content[0];
+            for (let i = 1; i < content.length; i++) {
+                if (quote === '"' && content[i] === '\\') {
+                    i++;
+                    continue;
+                }
+                if (content[i] === quote)
+                    return i + 1;
+            }
+        }
+        return 0;
+    }
+    readKey(line) {
+        const content = line.content;
+        if (content.startsWith('<<')) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.MERGE_KEY_FORBIDDEN, line.number);
+        }
+        if (content.startsWith('&') || content.startsWith('*')) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.ALIAS_FORBIDDEN, line.number);
+        }
+        if (content.startsWith('!')) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.TAG_FORBIDDEN, line.number);
+        }
+        if (content.startsWith('?') || content.startsWith('[') || content.startsWith('{')) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.UNSUPPORTED, line.number);
+        }
+        if (!KEY_HEAD.test(content)) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+        }
+        const tokenLength = this.keyTokenLength(content);
+        const colon = content.indexOf(':', tokenLength);
+        const rawKey = content.slice(0, colon).trim();
+        const key = rawKey.startsWith('"') || rawKey.startsWith("'")
+            ? this.parseQuoted(rawKey, line)
+            : rawKey;
+        if (key.length > this.profile.maxScalarLength) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.SCALAR_LIMIT, line.number);
+        }
+        if (this.profile.forbiddenKeys.includes(key)) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.FORBIDDEN_KEY, line.number);
+        }
+        return key;
+    }
+    parseValue(rest, indent, depth, line) {
+        if (rest === '') {
+            const next = this.peek();
+            if (next && next.indent === indent && this.isSequenceEntry(next.content)) {
+                this.checkDepth(depth + 1, next);
+                return this.parseSequence(indent, depth + 1);
+            }
+            return this.parseIndentedValue(indent, depth + 1, line);
+        }
+        if (rest[0] === '|' || rest[0] === '>') {
+            return this.parseBlockScalar(rest, indent, line);
+        }
+        this.countNode(line);
+        return this.parseScalar(rest, line);
+    }
+    /** Read the nested block owned by a line, or null when there is none. */
+    parseIndentedValue(indent, depth, owner) {
+        const next = this.peek();
+        if (!next || next.indent <= indent) {
+            this.countNode(owner);
+            return null;
+        }
+        this.checkDepth(depth, next);
+        return this.parseNode(next.indent, depth);
+    }
+    // ---------------------------------------------------------------------------
+    // Scalars
+    // ---------------------------------------------------------------------------
+    parseScalar(raw, line) {
+        if (raw.startsWith('&') || raw.startsWith('*')) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.ALIAS_FORBIDDEN, line.number);
+        }
+        if (raw.startsWith('!')) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.TAG_FORBIDDEN, line.number);
+        }
+        if (raw === '[]') {
+            this.countNode(line);
+            return [];
+        }
+        if (raw === '{}') {
+            this.countNode(line);
+            return Object.create(null);
+        }
+        if (raw.startsWith('[') || raw.startsWith('{') || raw.startsWith('%') || raw.startsWith('`')) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.UNSUPPORTED, line.number);
+        }
+        if (raw.startsWith('"') || raw.startsWith("'")) {
+            const value = this.parseQuoted(raw, line);
+            this.checkScalarLength(value, line);
+            return value;
+        }
+        this.checkScalarLength(raw, line);
+        return this.resolvePlain(raw);
+    }
+    checkScalarLength(value, line) {
+        if (value.length > this.profile.maxScalarLength) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.SCALAR_LIMIT, line.number);
+        }
+    }
+    resolvePlain(raw) {
+        if (raw === '~' || raw === 'null' || raw === 'Null' || raw === 'NULL')
+            return null;
+        if (raw === 'true' || raw === 'True' || raw === 'TRUE')
+            return true;
+        if (raw === 'false' || raw === 'False' || raw === 'FALSE')
+            return false;
+        if (/^-?(?:0|[1-9][0-9]*)$/.test(raw)) {
+            const parsed = Number(raw);
+            return Number.isSafeInteger(parsed) ? parsed : raw;
+        }
+        if (/^-?(?:0|[1-9][0-9]*)\.[0-9]+$/.test(raw))
+            return Number(raw);
+        return raw;
+    }
+    parseQuoted(raw, line) {
+        const quote = raw[0];
+        if (raw.length < 2 || !raw.endsWith(quote)) {
+            throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+        }
+        const body = raw.slice(1, -1);
+        if (quote === "'") {
+            let out = '';
+            for (let i = 0; i < body.length; i++) {
+                if (body[i] === "'") {
+                    if (body[i + 1] !== "'")
+                        throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+                    i++;
+                }
+                out += body[i];
+            }
+            return out;
+        }
+        let out = '';
+        for (let i = 0; i < body.length; i++) {
+            const ch = body[i];
+            if (ch !== '\\') {
+                if (ch === '"')
+                    throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+                out += ch;
+                continue;
+            }
+            const escape = body[++i];
+            switch (escape) {
+                case '"':
+                case '\\':
+                case '/':
+                    out += escape;
+                    break;
+                case 'n':
+                    out += '\n';
+                    break;
+                case 't':
+                    out += '\t';
+                    break;
+                case 'r':
+                    out += '\r';
+                    break;
+                case 'u': {
+                    const hex = body.slice(i + 1, i + 5);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+                        throw new SkillYamlError(exports.SkillYamlErrorCode.SYNTAX, line.number);
+                    }
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 4;
+                    break;
+                }
+                default:
+                    throw new SkillYamlError(exports.SkillYamlErrorCode.UNSUPPORTED, line.number);
+            }
+        }
+        return out;
+    }
+    /** Literal (`|`) and folded (`>`) block scalars with `-`/`+` chomping. */
+    parseBlockScalar(header, indent, owner) {
+        const match = /^([|>])([-+]?)$/.exec(header.trim());
+        if (!match)
+            throw new SkillYamlError(exports.SkillYamlErrorCode.UNSUPPORTED, owner.number);
+        const [, style, chomp] = match;
+        const collected = [];
+        let blockIndent = -1;
+        while (this.cursor < this.lines.length) {
+            const line = this.lines[this.cursor];
+            const isBlank = line.raw.trim() === '';
+            if (!isBlank && line.indent <= indent)
+                break;
+            if (!isBlank && blockIndent === -1)
+                blockIndent = line.indent;
+            collected.push(isBlank ? '' : line.raw.slice(blockIndent));
+            this.cursor++;
+        }
+        while (collected.length > 0 && collected[collected.length - 1] === '')
+            collected.pop();
+        this.countNode(owner);
+        let body;
+        if (style === '|') {
+            body = collected.join('\n');
+        }
+        else {
+            body = collected.reduce((acc, current, index) => {
+                if (index === 0)
+                    return current;
+                const previous = collected[index - 1];
+                if (current === '' || previous === '')
+                    return `${acc}\n${current}`;
+                return `${acc} ${current}`;
+            }, '');
+        }
+        if (chomp !== '-' && collected.length > 0)
+            body += '\n';
+        this.checkScalarLength(body, owner);
+        return body;
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Parse a YAML document under the safe profile.
+ *
+ * @param input Document bytes or text
+ * @param profile Bounds to enforce; defaults to {@link SKILL_YAML_SAFE_PROFILE}
+ * @returns The parsed value; mappings have a null prototype
+ * @throws SkillYamlError for every rejection, including plain syntax errors
+ */
+function parseSkillYaml(input, profile = skills_1.SKILL_YAML_SAFE_PROFILE) {
+    if (profile.allowAliases || profile.allowCustomTags) {
+        // The subset has no way to honour aliases or tags, so a profile that asks
+        // for them would silently under-enforce rather than parse them.
+        throw new SkillYamlError(exports.SkillYamlErrorCode.UNSUPPORTED);
+    }
+    const text = decodeUtf8(input, profile.maxBytes);
+    return new Parser(toLines(text), profile).parseDocument();
+}
+/**
+ * Extract and parse the YAML frontmatter of a Markdown document.
+ *
+ * Used for `SKILL.md`, whose frontmatter must agree with the manifest. The
+ * frontmatter is parsed under the same profile as the manifest: it is authored
+ * by the same untrusted publisher.
+ *
+ * @returns The parsed frontmatter, or null when the document has none
+ * @throws SkillYamlError when frontmatter is present but violates the profile
+ */
+function parseSkillFrontmatter(markdown, profile = skills_1.SKILL_YAML_SAFE_PROFILE) {
+    const normalized = markdown.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n'))
+        return null;
+    const end = normalized.indexOf('\n---', 3);
+    if (end === -1)
+        return null;
+    return parseSkillYaml(normalized.slice(4, end + 1), profile);
+}