dsh-plugin-inspector 0.1.0

package/lib/cordis-yaml.js

@@ -0,0 +1,393 @@
+/**
+ * Parsing a Cordis patch layer with the harness's own `!!js` dialect, and
+ * modelling it the way `applyEntryPatches` does.
+ *
+ * The dialect is transcribed from `dsh/scripts/verify-cordis-config.ts` and
+ * `dsh/vendor/include/src/index.ts`: `yaml.JSON_SCHEMA` extended with one
+ * scalar type for `tag:yaml.org,2002:js`, whose constructor produces an inert
+ * `{ __jsExpr }` node. **The expression text is never evaluated here.** Where
+ * the harness would call `new Function('ctx', 'expr', 'with (ctx) { return
+ * eval(expr) }')`, this module only ever compiles `return (expr)` to learn
+ * whether it parses, and parses it a second time with the TypeScript parser to
+ * classify what it reaches. Neither compiles-and-calls.
+ *
+ * js-yaml is pinned to the harness's `^4.2.0`. Parsing the same bytes
+ * differently from the runtime would make every downstream result unsound.
+ * @module dsh-plugin-inspector/cordis-yaml
+ */
+import yaml from 'js-yaml';
+import ts from 'typescript';
+import { HARNESS_INERT_CALLS, STATIC_ENTRY_FIELDS } from "./knowledge.js";
+/** Module specifiers whose `config` holds other rows rather than plugin data. */
+const TREE_CARRIERS = new Set([
+    '@deepseek-ai/cordis-plugin-group',
+    '@deepseek-ai/cordis-plugin-include',
+    'cordis:include',
+]);
+const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
+    kind: 'scalar',
+    resolve: data => typeof data === 'string',
+    construct: (data) => {
+        if (typeof data !== 'string')
+            throw new TypeError('!!js requires a scalar string');
+        return { __jsExpr: data };
+    },
+});
+/**
+ * The entry-list dialect: JSON schema plus `!!js`. Deliberately *not*
+ * `DEFAULT_SCHEMA`, which would also accept `!!python`, `!!binary` and friends
+ * — matching the harness exactly means a tag the harness rejects is rejected
+ * here too, and shows up as a finding rather than as parsed data.
+ */
+export const patchSchema = yaml.JSON_SCHEMA.extend(jsExprType);
+/** Every classification, in the order the report tallies them. */
+export const EXPRESSION_CLASSES = [
+    'literal', 'inert-read', 'harness-call', 'call', 'mutation', 'module-access', 'unparseable',
+];
+/** Nodes one patch layer may be walked through before the walk gives up. */
+export const MAX_WALK_NODES = 200_000;
+/** Nesting one patch layer may reach before the walk gives up. */
+export const MAX_WALK_DEPTH = 200;
+/**
+ * Charge one node against the budget, and refuse a node already walked.
+ * @param budget - the shared budget.
+ * @param value - the node about to be walked.
+ * @param depth - the current nesting depth.
+ * @returns true when the walk may descend into this node.
+ */
+function admit(budget, value, depth) {
+    if (budget.limit !== null)
+        return false;
+    if (depth > MAX_WALK_DEPTH) {
+        budget.limit = 'depth';
+        return false;
+    }
+    budget.nodes += 1;
+    if (budget.nodes > MAX_WALK_NODES) {
+        budget.limit = 'nodes';
+        return false;
+    }
+    if (typeof value !== 'object' || value === null)
+        return true;
+    if (budget.visited.has(value))
+        return false;
+    budget.visited.add(value);
+    return true;
+}
+/** Thrown when the patch file cannot be parsed as an entry list. */
+export class PatchParseError extends Error {
+    /** True when the failure is a `!js` single-bang tag, which never loads anywhere. */
+    singleBangTag;
+    /**
+     * @param message - the underlying parse diagnostic.
+     * @param singleBangTag - whether the raw text contains a `!js` tag.
+     */
+    constructor(message, singleBangTag) {
+        super(message);
+        this.singleBangTag = singleBangTag;
+    }
+}
+/**
+ * Whether a value is a plain object. Patch rows are objects; anything else at a
+ * row position is malformed input from an untrusted file.
+ * @param value - the parsed value.
+ * @returns true for a non-null, non-array object.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a value is a `!!js` node. Matches the loader's own predicate.
+ * @param value - the parsed value.
+ * @returns true for an expression node.
+ */
+export function isJsExpr(value) {
+    return isRecord(value) && typeof value.__jsExpr === 'string';
+}
+/**
+ * Classify what a `!!js` expression can reach, by parsing it — never running
+ * it. Precedence is by reach: module access beats mutation beats an unknown
+ * call beats a known-inert call beats a read, so an expression is reported at
+ * its most capable form.
+ *
+ * The grading is by reach, not by syntactic form. `dshHomePath('sessions')` is
+ * a `CallExpression` and so is `steal()`, but the first is a helper the harness
+ * itself provides to these expressions and uses in its own shipped bundle,
+ * while the second names something this tool cannot resolve. Grading both as
+ * the same thing puts the harness's own configuration at the same severity as
+ * an attack and teaches the reader to skip the class.
+ * @param expression - the raw expression text.
+ * @returns the classification and, when it does not parse, the diagnostic.
+ */
+export function classifyExpression(expression) {
+    try {
+        // Compilation only. The Function constructor never executes the body, and
+        // the resulting function is discarded without being called.
+        new Function(`return (${expression})`);
+    }
+    catch (error) {
+        return { class: 'unparseable', parseError: error instanceof Error ? error.message : String(error) };
+    }
+    const source = ts.createSourceFile('expr.ts', `(${expression})`, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
+    let sawCall = false;
+    let sawHarnessCall = false;
+    let sawMutation = false;
+    let sawModuleAccess = false;
+    let sawIdentifier = false;
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && MODULE_REACHING_NAMES.has(node.text))
+            sawModuleAccess = true;
+        if (ts.isPropertyAccessExpression(node) && MODULE_REACHING_NAMES.has(node.name.text))
+            sawModuleAccess = true;
+        if (node.kind === ts.SyntaxKind.ImportKeyword)
+            sawModuleAccess = true;
+        if (ts.isBinaryExpression(node) && ASSIGNMENT_OPERATORS.has(node.operatorToken.kind))
+            sawMutation = true;
+        if (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) {
+            if (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken)
+                sawMutation = true;
+        }
+        if (ts.isDeleteExpression(node))
+            sawMutation = true;
+        if (ts.isCallExpression(node)) {
+            if (isInertCall(node))
+                sawHarnessCall = true;
+            else
+                sawCall = true;
+        }
+        if (ts.isNewExpression(node))
+            sawCall = true;
+        if (ts.isIdentifier(node))
+            sawIdentifier = true;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(source, visit);
+    if (sawModuleAccess)
+        return { class: 'module-access' };
+    if (sawMutation)
+        return { class: 'mutation' };
+    if (sawCall)
+        return { class: 'call' };
+    if (sawHarnessCall)
+        return { class: 'harness-call' };
+    if (sawIdentifier)
+        return { class: 'inert-read' };
+    return { class: 'literal' };
+}
+/** Names that reach the module system, the global object, or the evaluator. */
+const MODULE_REACHING_NAMES = new Set([
+    'require', 'eval', 'Function', 'globalThis', 'global', 'getBuiltinModule',
+    'constructor', 'binding', 'dlopen', '__proto__',
+]);
+/** Binary operator kinds that write. */
+const ASSIGNMENT_OPERATORS = new Set([
+    ts.SyntaxKind.EqualsToken,
+    ts.SyntaxKind.PlusEqualsToken,
+    ts.SyntaxKind.MinusEqualsToken,
+    ts.SyntaxKind.AsteriskEqualsToken,
+    ts.SyntaxKind.SlashEqualsToken,
+    ts.SyntaxKind.QuestionQuestionEqualsToken,
+    ts.SyntaxKind.BarBarEqualsToken,
+    ts.SyntaxKind.AmpersandAmpersandEqualsToken,
+]);
+/**
+ * Calls the harness itself puts in scope for these expressions, or that only
+ * read the current process's own identity — `cwd: !!js process.cwd()` and
+ * `root: !!js dshHomePath('sessions')` are both from the shipped bundles.
+ * Grading these as an unknown call would fire on the reference configuration.
+ * @param node - the call expression.
+ * @returns true when the callee is a catalogued harness or process helper.
+ */
+function isInertCall(node) {
+    const callee = node.expression;
+    if (ts.isIdentifier(callee))
+        return HARNESS_INERT_CALLS.has(callee.text);
+    if (!ts.isPropertyAccessExpression(callee))
+        return false;
+    if (!ts.isIdentifier(callee.expression))
+        return false;
+    return HARNESS_INERT_CALLS.has(`${callee.expression.text}.${callee.name.text}`);
+}
+/**
+ * Collect every `!!js` node below a value, with its diagnostic path. Mirrors
+ * `collectExpressionPaths` in the harness's verify script.
+ * @param value - the value to walk.
+ * @param path - the diagnostic path prefix.
+ * @param slot - the slot these expressions occupy.
+ * @param sink - accumulators, including the walk budget.
+ * @param depth - the current nesting depth.
+ */
+function collect(value, path, slot, sink, depth) {
+    if (!admit(sink.budget, value, depth))
+        return;
+    if (isJsExpr(value)) {
+        const classified = classifyExpression(value.__jsExpr);
+        sink.expressions.push({
+            path,
+            expression: value.__jsExpr,
+            slot,
+            classification: classified.class,
+            ...classified.parseError !== undefined ? { parseError: classified.parseError } : {},
+        });
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries())
+            collect(item, `${path}[${index}]`, slot, sink, depth + 1);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, child] of Object.entries(value))
+        collect(child, `${path}.${key}`, slot, sink, depth + 1);
+}
+/**
+ * Collect the expressions of one row or patch, applying the loader's rule:
+ * `config` is interpolated recursively, `disabled` only at its own top level,
+ * and every other field stays literal so an expression there is inert data.
+ * @param entry - the row or patch object.
+ * @param path - its diagnostic path.
+ * @param sink - accumulators, including the walk budget.
+ * @param configIsData - false when `config` holds child rows rather than plugin data.
+ * @param depth - the current nesting depth.
+ */
+function collectEntryExpressions(entry, path, sink, configIsData, depth) {
+    if (configIsData && 'config' in entry)
+        collect(entry.config, `${path}.config`, 'config', sink, depth + 1);
+    if ('disabled' in entry) {
+        const disabled = entry.disabled;
+        const slot = isJsExpr(disabled) ? 'disabled' : 'inert';
+        collect(disabled, `${path}.disabled`, slot, sink, depth + 1);
+    }
+    for (const field of STATIC_ENTRY_FIELDS) {
+        if (field in entry)
+            collect(entry[field], `${path}.${field}`, 'inert', sink, depth + 1);
+    }
+}
+/**
+ * The service names an `isolate` or `intercept` entry field names. The loader
+ * reads both as a dictionary keyed by service name (`entry.options.isolate?.[name]`).
+ * @param value - the raw field value.
+ * @returns the service names, or an empty list when the field is absent or malformed.
+ */
+function serviceNames(value) {
+    return isRecord(value) ? Object.keys(value) : [];
+}
+/**
+ * Whether a row carries other rows in its `config` rather than plugin data.
+ * The loader keeps such a config literal and evaluates each child expression in
+ * the child's own fiber instead.
+ * @param entry - the row.
+ * @returns true for a group or include carrier.
+ */
+function isTreeCarrier(entry) {
+    return entry.group === true || (typeof entry.name === 'string' && TREE_CARRIERS.has(entry.name));
+}
+/**
+ * Walk one inserted row and, when it carries children, its children too.
+ * @param value - the row.
+ * @param path - its diagnostic path.
+ * @param intoGroupId - the group this row is inserted into, or `null`.
+ * @param sink - accumulators.
+ * @param depth - the current nesting depth.
+ */
+function walkRow(value, path, intoGroupId, sink, depth) {
+    if (!isRecord(value))
+        return;
+    if (!admit(sink.budget, value, depth))
+        return;
+    const carrier = isTreeCarrier(value);
+    sink.inserts.push({
+        path,
+        id: typeof value.id === 'string' ? value.id : null,
+        name: typeof value.name === 'string' ? value.name : null,
+        config: value.config,
+        intoGroupId,
+        isolate: serviceNames(value.isolate),
+        intercept: serviceNames(value.intercept),
+    });
+    collectEntryExpressions(value, path, sink, !carrier, depth);
+    if (!carrier)
+        return;
+    const config = value.config;
+    if (Array.isArray(config)) {
+        for (const [index, child] of config.entries()) {
+            walkRow(child, `${path}.config[${index}]`, typeof value.id === 'string' ? value.id : null, sink, depth + 1);
+        }
+        return;
+    }
+    if (isRecord(config) && Array.isArray(config.patches)) {
+        walkPatchList(config.patches, `${path}.config.patches`, sink, depth + 1);
+    }
+}
+/**
+ * Walk a patch list, separating inserts from overrides exactly as
+ * `applyEntryPatches` does: `insert` is checked first and wins outright, so a
+ * patch carrying both `insert` and override keys applies only the insert.
+ * @param list - the patch array.
+ * @param prefix - diagnostic path prefix.
+ * @param sink - accumulators.
+ * @param depth - the current nesting depth.
+ */
+function walkPatchList(list, prefix, sink, depth) {
+    for (const [index, patch] of list.entries()) {
+        const path = `${prefix}[${index}]`;
+        if (!isRecord(patch))
+            continue;
+        if (!admit(sink.budget, patch, depth))
+            continue;
+        const id = typeof patch.id === 'string' ? patch.id : null;
+        if (Array.isArray(patch.insert)) {
+            for (const [rowIndex, row] of patch.insert.entries()) {
+                walkRow(row, `${path}.insert[${rowIndex}]`, id, sink, depth + 1);
+            }
+            continue;
+        }
+        if (id === null)
+            continue;
+        const overriddenKeys = Object.keys(patch).filter(key => key !== 'id' && key !== 'insert' && key !== 'name');
+        sink.overrides.push({
+            path,
+            id,
+            nameGuard: typeof patch.name === 'string' ? patch.name : null,
+            overriddenKeys,
+            disabled: 'disabled' in patch ? patch.disabled : undefined,
+            config: patch.config,
+        });
+        collectEntryExpressions(patch, path, sink, true, depth);
+    }
+}
+/**
+ * Parse a patch layer.
+ * @param file - package-relative path, used in findings.
+ * @param text - the YAML text.
+ * @returns the modelled patch document.
+ * @throws PatchParseError when the text is not a loadable entry list.
+ */
+export function parsePatchDocument(file, text) {
+    let document;
+    try {
+        document = yaml.load(text, { schema: patchSchema });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new PatchParseError(message, /(?<!!)!js(?![a-zA-Z0-9_-])/.test(text));
+    }
+    if (!Array.isArray(document)) {
+        throw new PatchParseError('a patch layer must be a top-level array of entries', false);
+    }
+    const sink = {
+        overrides: [],
+        inserts: [],
+        expressions: [],
+        budget: { visited: new WeakSet(), nodes: 0, limit: null },
+    };
+    walkPatchList(document, '', sink, 0);
+    return {
+        file,
+        overrides: sink.overrides,
+        inserts: sink.inserts,
+        expressions: sink.expressions,
+        limit: sink.budget.limit,
+    };
+}

package/lib/files.js

@@ -0,0 +1,131 @@
+/**
+ * Classifying the files inside an analysed package, and formatting excerpts of
+ * them for evidence.
+ * @module dsh-plugin-inspector/files
+ */
+/** Extensions the TypeScript parser is asked to read. */
+const SOURCE_EXTENSIONS = [
+    '.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs',
+];
+/** Longest evidence excerpt kept in a finding. */
+const SNIPPET_LIMIT = 160;
+/**
+ * Whether a path is JavaScript or TypeScript source this tool will parse.
+ * Declaration files are excluded: they carry types, never behavior.
+ * @param path - package-relative path.
+ * @returns true when the file should be parsed.
+ */
+export function isSourceFile(path) {
+    if (path.endsWith('.d.ts') || path.endsWith('.d.mts') || path.endsWith('.d.cts'))
+        return false;
+    return SOURCE_EXTENSIONS.some(extension => path.endsWith(extension));
+}
+/**
+ * Whether a path is markdown that can reach the model verbatim.
+ *
+ * The reach is conditional and PLAN.md §6.1 says so: a `SKILL.md` inside an npm
+ * package is only discovered when the plugin registers it through
+ * `ctx.skills`, when a patch row redirects a skill root into the package, or
+ * when something copies it into the user's workspace. This predicate answers
+ * "is this the kind of file that would reach the model if it were found", not
+ * "will it be found".
+ * @param path - package-relative POSIX path.
+ * @returns true for skill and agent-instruction markdown.
+ */
+export function isModelVisibleText(path) {
+    const segments = path.split('/');
+    const base = segments.at(-1) ?? '';
+    if (base === 'SKILL.md' || base === 'AGENTS.md' || base === 'CLAUDE.md')
+        return true;
+    // The filesystem provider scans a skill root at depth 1: `<root>/<name>.md`
+    // or `<root>/<name>/SKILL.md`. The bare `.md` form is only a skill when it
+    // sits directly inside a directory named `skills`.
+    return segments.length >= 2 && segments.at(-2) === 'skills' && base.endsWith('.md');
+}
+/**
+ * Whether a path is a Cordis config file, using the harness's own naming
+ * convention from `scripts/cordis-config-files.ts`.
+ * @param path - package-relative POSIX path.
+ * @returns true for a cordis YAML file.
+ */
+export function isCordisConfigFile(path) {
+    const base = path.split('/').at(-1) ?? '';
+    return /cordis/.test(base) && (base.endsWith('.yml') || base.endsWith('.yaml'));
+}
+/**
+ * Resolve a manifest-declared path to the package-relative POSIX form used as
+ * map keys, or report that it leaves the package.
+ *
+ * Only `..` escapes. An absolute path does **not**: the launcher resolves the
+ * patch as `join(packageDir, declared)` (`packages/boot/app-boot/src/profile.ts`),
+ * and `join` re-roots an absolute second argument *inside* the first, so
+ * `join('/…/pkg', '/etc/passwd')` is `/…/pkg/etc/passwd`. A leading slash
+ * therefore names a file the package does not ship, not a file outside it.
+ * @param declared - the path exactly as the manifest declares it.
+ * @returns the normalised package-relative path, or `null` when it escapes.
+ */
+export function normalizePackagePath(declared) {
+    const segments = [];
+    for (const segment of declared.replace(/^[a-zA-Z]:/, '').split(/[\\/]/)) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (segments.length === 0)
+                return null;
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return segments.join('/');
+}
+/**
+ * Render a value as JSON-like evidence without walking a graph as a tree.
+ * A YAML anchor makes one node reachable by many paths, so `JSON.stringify` on
+ * a patch row's `config` can be asked to serialise billions of nodes from a
+ * few hundred bytes of input. This stops at a depth and a length instead.
+ * @param value - the value to describe.
+ * @param maxDepth - how far to descend before writing an ellipsis.
+ * @param limit - the longest string to return.
+ * @returns the bounded rendering.
+ */
+export function boundedJson(value, maxDepth = 4, limit = SNIPPET_LIMIT * 2) {
+    const seen = new WeakSet();
+    const render = (node, depth) => {
+        if (node === null || typeof node !== 'object')
+            return JSON.stringify(node) ?? 'null';
+        if (seen.has(node))
+            return '"…(repeated)"';
+        if (depth >= maxDepth)
+            return Array.isArray(node) ? '[…]' : '{…}';
+        seen.add(node);
+        if (Array.isArray(node))
+            return `[${node.slice(0, 8).map(item => render(item, depth + 1)).join(',')}]`;
+        const entries = Object.entries(node).slice(0, 16);
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${render(item, depth + 1)}`).join(',')}}`;
+    };
+    const text = render(value, 0);
+    return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+/**
+ * Reduce text to a single-line excerpt safe to print in a report.
+ * @param text - the source text.
+ * @param limit - maximum characters to keep.
+ * @returns the collapsed, truncated excerpt.
+ */
+export function snippet(text, limit = SNIPPET_LIMIT) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit - 1)}…`;
+}
+/**
+ * Convert a character offset to a `line:column` locator, both 1-based.
+ * @param text - the file text.
+ * @param offset - the character offset.
+ * @returns the locator.
+ */
+export function lineColumn(text, offset) {
+    const before = text.slice(0, offset);
+    const line = before.split('\n').length;
+    const column = offset - (before.lastIndexOf('\n') + 1) + 1;
+    return `${line}:${column}`;
+}

package/lib/index.js

@@ -0,0 +1,22 @@
+/**
+ * `dsh-plugin-inspector` — static pre-install analysis of a DeepSeek Harness
+ * plugin.
+ *
+ * The library face of the tool, for callers that want the report rather than
+ * the exit code. {@link inspect} decodes a plugin directory or npm tarball,
+ * runs the three check tiers over the decoded form, and returns a
+ * {@link Report}. It never installs, builds, imports, spawns, or evaluates
+ * anything from the analysed package.
+ *
+ * The ceiling is triage, not containment. See `README.md` §Limitations.
+ * @module dsh-plugin-inspector
+ */
+export { exceedsThreshold, inspect, TOOL_NAME, TOOL_VERSION } from "./inspect.js";
+export { renderHuman, renderJson } from "./report.js";
+export { classifyExpression, isJsExpr, parsePatchDocument, patchSchema, PatchParseError, } from "./cordis-yaml.js";
+export { declaredPackages, ManifestError, parseManifest } from "./manifest.js";
+export { DEFAULT_LIMITS, loadSource, SourceError } from "./source.js";
+export { globMatch, publishSet } from "./publish.js";
+export { INJECTION_RULES, scanInjection } from "./injection.js";
+export { compareFindings, SEVERITIES, SEVERITY_RANK, summarize, } from "./model.js";
+export { CORE_ROWS, CORE_ROW_IDS, HARNESS_BUNDLE_PACKAGES, HARNESS_REFERENCE, SEAM_KEYS, SECURITY_ROW_IDS, WATERFALL_EVENTS, } from "./knowledge.js";

package/lib/injection.js

@@ -0,0 +1,90 @@
+/**
+ * Prompt-injection heuristics, applied to model-visible text only.
+ *
+ * "Model-visible" is a narrow set on purpose: shipped skill and
+ * agent-instruction markdown, and the `description` string of a registered
+ * tool. Those reach the model verbatim, unescaped and uncapped. Ordinary source
+ * comments do not, and scanning them would produce a stream of false positives
+ * from documentation that happens to quote an attack.
+ *
+ * These are heuristics over natural language. They will miss a rephrased
+ * instruction and they will occasionally fire on a legitimate document that
+ * discusses prompt injection. Both directions are stated in the finding.
+ * @module dsh-plugin-inspector/injection
+ */
+/**
+ * The rule table. Each pattern targets an instruction that only makes sense if
+ * the author expects a model rather than a person to read it.
+ */
+export const INJECTION_RULES = [
+    {
+        id: 'override-prior-instructions',
+        pattern: /\b(?:ignore|disregard|forget|override)\b[^.\n]{0,40}\b(?:previous|prior|above|earlier|all)\b[^.\n]{0,20}\b(?:instruction|prompt|rule|direction|guideline)/i,
+        meaning: 'tells the model to discard instructions it was already given',
+    },
+    {
+        id: 'role-reassignment',
+        pattern: /\b(?:you are now|from now on,? you (?:are|will|must|should)|your new (?:role|task|instruction))\b/i,
+        meaning: 'reassigns the model\'s role',
+    },
+    {
+        id: 'conceal-from-user',
+        pattern: /\b(?:do not|don't|never)\b[^.\n]{0,30}\b(?:tell|inform|mention|reveal|show|display|report)\b[^.\n]{0,20}\buser\b/i,
+        meaning: 'instructs the model to hide something from the user',
+    },
+    {
+        id: 'bypass-approval',
+        pattern: /\bwithout\b[^.\n]{0,30}\b(?:asking|confirming|approval|permission|prompting)\b/i,
+        meaning: 'instructs the model to act without the approval step',
+    },
+    {
+        id: 'credential-exfiltration',
+        pattern: /\b(?:send|post|upload|transmit|exfiltrate|forward|report)\b[^.\n]{0,60}\b(?:api[_ -]?key|access[_ -]?token|secret|credential|password|\.env|id_rsa|\.npmrc)\b/i,
+        meaning: 'instructs the model to move a credential somewhere',
+    },
+    {
+        id: 'system-prompt-disclosure',
+        pattern: /\b(?:reveal|print|output|repeat|show|dump)\b[^.\n]{0,30}\b(?:system prompt|initial instructions|your instructions)\b/i,
+        meaning: 'asks the model to disclose its system prompt',
+    },
+    {
+        id: 'pipe-to-shell',
+        pattern: /\b(?:curl|wget)\b[^\n|]{0,120}\|\s*(?:sudo\s+)?(?:ba|z|k)?sh\b/i,
+        meaning: 'contains a download-and-execute shell pipeline',
+    },
+    {
+        id: 'encoded-payload',
+        pattern: /\b(?:base64\s+(?:-d|--decode)|atob\s*\(|echo\s+[A-Za-z0-9+/]{40,}={0,2}\s*\|)/,
+        meaning: 'contains an encoded payload the reader cannot evaluate',
+    },
+    {
+        id: 'hidden-characters',
+        pattern: /[\u200b-\u200f\u202a-\u202e\u2060-\u2064\ufeff]|[\u{E0000}-\u{E007F}]/u,
+        meaning: 'contains zero-width or bidirectional-control characters, which change what a human reader sees but not what the model reads',
+    },
+    {
+        id: 'hidden-html-instruction',
+        pattern: /<!--[^]{0,400}?\b(?:you (?:must|should|are)|instruction|assistant|ignore)\b[^]{0,400}?-->/i,
+        meaning: 'hides an instruction inside an HTML comment, invisible in rendered markdown',
+    },
+];
+/**
+ * Scan model-visible text for injection phrasing.
+ * @param text - the text a model would receive.
+ * @returns one match per rule that fired, at its first occurrence.
+ */
+export function scanInjection(text) {
+    const matches = [];
+    for (const rule of INJECTION_RULES) {
+        const found = rule.pattern.exec(text);
+        if (found === null)
+            continue;
+        matches.push({
+            ruleId: rule.id,
+            meaning: rule.meaning,
+            index: found.index,
+            excerpt: text.slice(Math.max(0, found.index - 20), found.index + found[0].length + 20),
+        });
+    }
+    return matches;
+}