dsh-plugin-inspector 0.1.0

package/lib/source.js

@@ -0,0 +1,410 @@
+/**
+ * Reading the package under analysis without installing, building, or running
+ * any part of it.
+ *
+ * A directory is walked directly. A tarball is decoded **entirely in memory** —
+ * nothing is ever written to disk. That is a safety property, not an
+ * optimisation: it makes tar path traversal (`../../.ssh/authorized_keys`)
+ * structurally impossible rather than something a filter has to catch, and it
+ * lets a test assert that analysing a hostile tarball touched no file.
+ *
+ * Every cap is enforced *while* bytes arrive, not after. A tar entry is
+ * abandoned the moment its running total passes {@link MAX_FILE_BYTES}, so a
+ * 27 MB tarball holding a 6 GB member costs 27 MB of decompression and no
+ * memory at all. Enforcing a cap on an already-materialised buffer is not a
+ * cap.
+ *
+ * Symbolic links are recorded and never followed, for the same reason: a link
+ * pointing outside the package is not part of the package.
+ * @module dsh-plugin-inspector/source
+ */
+import { createReadStream, openSync, readdirSync, readFileSync, readSync, closeSync, statSync } from 'node:fs';
+import { join, posix, relative, resolve, sep } from 'node:path';
+import { PassThrough, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { Parser } from 'tar';
+import { publishSet, TARBALL_PUBLISH_SET } from "./publish.js";
+/** Largest single file the analyzer will hold in memory. */
+export const MAX_FILE_BYTES = 4 * 1024 * 1024;
+/** Largest total payload the analyzer will hold in memory. */
+export const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+/** Largest number of files the analyzer will consider. */
+export const MAX_ENTRIES = 10_000;
+/** The shipping ceilings. Tests substitute smaller ones to exercise each cap. */
+export const DEFAULT_LIMITS = {
+    maxFileBytes: MAX_FILE_BYTES,
+    maxTotalBytes: MAX_TOTAL_BYTES,
+    maxEntries: MAX_ENTRIES,
+};
+/** Directories never descended into: not shipped, and not the package's own code. */
+const SKIPPED_DIRECTORIES = new Set([
+    'node_modules', '.git', '.pnpm-store', '.yarn', 'coverage', '.nyc_output',
+]);
+/** Thrown when the target cannot be read at all, which is exit code 2, not a finding. */
+export class SourceError extends Error {
+}
+/**
+ * Whether a buffer looks like binary content. A NUL byte in the first 8 KiB is
+ * the same cheap test `grep` and `git` use, and it is enough here: the point is
+ * only to avoid parsing bytes that are not source.
+ * @param buffer - the file content.
+ * @returns true when the file should be treated as opaque.
+ */
+function isBinary(buffer) {
+    return buffer.subarray(0, 8192).includes(0);
+}
+/**
+ * Charge one file against the entry count.
+ * @param collector - the shared accumulator.
+ * @param path - package-relative POSIX path.
+ * @returns true when the analyzer may go on to read it.
+ */
+function countEntry(collector, path) {
+    if (collector.entries >= collector.limits.maxEntries) {
+        collector.skipped.push({ path, reason: 'entry-cap' });
+        return false;
+    }
+    collector.entries += 1;
+    return true;
+}
+/**
+ * Record one already-read file against the size caps, storing its text when it
+ * is readable.
+ * @param collector - the shared accumulator.
+ * @param path - package-relative POSIX path.
+ * @param buffer - the file content.
+ */
+function store(collector, path, buffer) {
+    if (buffer.byteLength > collector.limits.maxFileBytes) {
+        collector.skipped.push({ path, reason: 'size-cap' });
+        return;
+    }
+    if (collector.bytes + buffer.byteLength > collector.limits.maxTotalBytes) {
+        collector.skipped.push({ path, reason: 'total-cap' });
+        return;
+    }
+    if (isBinary(buffer)) {
+        collector.skipped.push({ path, reason: 'binary' });
+        return;
+    }
+    collector.bytes += buffer.byteLength;
+    collector.files.set(path, buffer.toString('utf8'));
+}
+/**
+ * Walk a directory tree, never following symlinks, never descending into build
+ * or dependency directories, and reading only what the package would publish.
+ * @param root - absolute package root.
+ * @param directory - absolute directory currently being read.
+ * @param collector - the shared accumulator.
+ * @param published - the publish-set membership test.
+ */
+function walkDirectory(root, directory, collector, published) {
+    let entries;
+    try {
+        entries = readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        collector.skipped.push({ path: toPackagePath(root, directory), reason: 'unreadable' });
+        return;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const absolute = join(directory, entry.name);
+        const path = toPackagePath(root, absolute);
+        if (entry.isSymbolicLink()) {
+            if (published.includes(path))
+                collector.skipped.push({ path, reason: 'unreadable' });
+            continue;
+        }
+        if (entry.isDirectory()) {
+            if (SKIPPED_DIRECTORIES.has(entry.name))
+                continue;
+            walkDirectory(root, absolute, collector, published);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (!published.includes(path)) {
+            collector.unpublished += 1;
+            continue;
+        }
+        if (!countEntry(collector, path))
+            continue;
+        try {
+            // Size first, then read. `readFileSync` on an oversized file materialises
+            // it before any cap can reject it, which is the same mistake on the
+            // directory path that the tar reader had on the tarball path.
+            if (statSync(absolute).size > collector.limits.maxFileBytes) {
+                collector.skipped.push({ path, reason: 'size-cap' });
+                continue;
+            }
+            store(collector, path, readFileSync(absolute));
+        }
+        catch {
+            collector.skipped.push({ path, reason: 'unreadable' });
+        }
+    }
+}
+/**
+ * Convert an absolute path inside the package to the POSIX package-relative
+ * form every report and finding uses.
+ * @param root - absolute package root.
+ * @param absolute - absolute path inside it.
+ * @returns the package-relative POSIX path.
+ */
+function toPackagePath(root, absolute) {
+    return relative(root, absolute).split(sep).join(posix.sep);
+}
+/**
+ * Drop the tarball's single leading directory, which npm always sets to
+ * `package/`, so tarball paths and directory paths are directly comparable, and
+ * reject anything that still climbs out afterwards. Nothing is written from a
+ * tar entry, but a finding whose `file` reads `../../../../etc/passwd` claims a
+ * location the package does not have.
+ * @param entryPath - the raw tar entry path.
+ * @returns the package-relative path, or `undefined` when there is none.
+ */
+function stripRoot(entryPath) {
+    const normalized = entryPath.replace(/^\.\//, '');
+    const slash = normalized.indexOf('/');
+    if (slash < 0)
+        return undefined;
+    const remainder = normalized.slice(slash + 1);
+    if (remainder === '')
+        return undefined;
+    const segments = [];
+    for (const segment of remainder.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (segments.length === 0)
+                return undefined;
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return segments.length === 0 ? undefined : segments.join('/');
+}
+/**
+ * Decompressed tar bytes one tarball may produce before the read is abandoned.
+ *
+ * Eight times the in-memory ceiling. A plugin tarball is never this large, and
+ * one that is has already answered the only question worth asking about it.
+ */
+export const MAX_STREAM_BYTES = 8 * MAX_TOTAL_BYTES;
+/**
+ * A stage that fails the pipeline once the decompressed stream passes a
+ * ceiling. Nothing downstream keeps the bytes, but *producing* eight gigabytes
+ * from a 28 MB file still costs the time to inflate them, and a CI job that
+ * hangs for a minute on a hostile input is a denial of service with extra
+ * steps.
+ * @param limit - the ceiling in bytes.
+ * @returns the counting stage.
+ */
+function byteCeiling(limit) {
+    let total = 0;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            total += chunk.byteLength;
+            if (total > limit) {
+                callback(new SourceError(`decompresses to more than ${limit} bytes`));
+                return;
+            }
+            callback(null, chunk);
+        },
+    });
+}
+/**
+ * Whether a file begins with the gzip magic number, so a plain `.tar` is read
+ * as one rather than failing in the inflater.
+ * @param file - absolute path.
+ * @returns true when the file is gzipped.
+ */
+function isGzip(file) {
+    const handle = openSync(file, 'r');
+    try {
+        const header = Buffer.alloc(2);
+        readSync(handle, header, 0, 2, 0);
+        return header[0] === 0x1f && header[1] === 0x8b;
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+/**
+ * Decode an npm tarball into memory. The tar reader is only ever a `Parser`;
+ * no extraction call exists in this module, so there is no code path that can
+ * write a file.
+ *
+ * The pipeline is assembled by hand rather than through `tar.list({ file })`
+ * because that convenience path applies no backpressure between the inflater
+ * and the parser: the inflater runs ahead, and a tarball holding one very large
+ * member materialises gigabytes of it whatever the entry consumer does. A
+ * `stream.pipeline` of Node streams paces the inflater against the parser, and
+ * measured on the same 28 MB probe it holds the process at 96 MB instead of
+ * 4 GB.
+ *
+ * Errors thrown from the entry callbacks reach an EventEmitter, not the
+ * `await`, so every one of them is captured here and rethrown on the awaited
+ * path — an emitter-thrown `RangeError` that escapes becomes an uncaught
+ * exception and a raw stack trace on a user's terminal.
+ * @param file - absolute path to the `.tgz`.
+ * @param collector - the shared accumulator.
+ */
+async function readTarball(file, collector) {
+    const pending = [];
+    let failure = null;
+    const parser = new Parser({
+        onReadEntry: (entry) => {
+            if (entry.type !== 'File') {
+                entry.resume();
+                return;
+            }
+            const path = stripRoot(String(entry.path));
+            if (path === undefined) {
+                collector.skipped.push({ path: String(entry.path), reason: 'unreadable' });
+                entry.resume();
+                return;
+            }
+            if (!countEntry(collector, path)) {
+                entry.resume();
+                return;
+            }
+            pending.push(new Promise((done) => {
+                let chunks = [];
+                let size = 0;
+                let abandoned = null;
+                const abandon = (reason) => {
+                    abandoned = reason;
+                    chunks = [];
+                    entry.resume();
+                };
+                entry.on('data', (chunk) => {
+                    if (abandoned !== null)
+                        return;
+                    size += chunk.byteLength;
+                    if (size > collector.limits.maxFileBytes)
+                        return abandon('size-cap');
+                    if (collector.bytes + size > collector.limits.maxTotalBytes)
+                        return abandon('total-cap');
+                    chunks.push(chunk);
+                });
+                entry.on('end', () => {
+                    try {
+                        if (abandoned === null)
+                            store(collector, path, Buffer.concat(chunks));
+                        else
+                            collector.skipped.push({ path, reason: abandoned });
+                    }
+                    catch (error) {
+                        failure ??= error;
+                    }
+                    chunks = [];
+                    done();
+                });
+            }));
+        },
+    });
+    const inflate = isGzip(file) ? createGunzip() : new PassThrough();
+    await pipeline(createReadStream(file), inflate, byteCeiling(MAX_STREAM_BYTES), parser);
+    await Promise.all(pending);
+    if (failure !== null)
+        throw failure;
+}
+/**
+ * Read the `files`, `main`, and ignore rules a working tree publishes under,
+ * without trusting the manifest to be well formed — a hostile `package.json`
+ * whose `files` is a number must not stop the analysis.
+ *
+ * A manifest that is missing or is not JSON produces no rules rather than an
+ * error. Diagnosing that is `parseManifest`'s job and it says something more
+ * useful than this function could; failing here would replace "package.json is
+ * not valid JSON, at position 4" with "this is not an npm package".
+ * @param root - absolute package root.
+ * @returns the publish-set membership test.
+ */
+function directoryPublishSet(root) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        manifest = {};
+    }
+    const record = typeof manifest === 'object' && manifest !== null && !Array.isArray(manifest)
+        ? manifest
+        : {};
+    const files = record.files;
+    const main = record.main;
+    return publishSet({
+        files: Array.isArray(files) ? files.filter((entry) => typeof entry === 'string') : null,
+        main: typeof main === 'string' ? main : null,
+        npmignore: readOptional(join(root, '.npmignore')),
+        gitignore: readOptional(join(root, '.gitignore')),
+    });
+}
+/**
+ * Read a file that may not exist.
+ * @param path - absolute path.
+ * @returns the text, or `null`.
+ */
+function readOptional(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        // Absent, a directory, or unreadable: all three mean "no rules from here".
+        return null;
+    }
+}
+/**
+ * Read the package under analysis.
+ * @param target - a plugin directory, or a `.tgz` / `.tar.gz` npm tarball.
+ * @param limits - resource ceilings; defaults to {@link DEFAULT_LIMITS}.
+ * @returns the decoded package.
+ * @throws SourceError when the target does not exist, is not a readable
+ * tarball, or holds no `package.json`.
+ */
+export async function loadSource(target, limits = DEFAULT_LIMITS) {
+    const path = resolve(target);
+    let stats;
+    try {
+        stats = statSync(path);
+    }
+    catch {
+        throw new SourceError(`cannot read target: ${path}`);
+    }
+    const collector = { files: new Map(), skipped: [], limits, bytes: 0, entries: 0, unpublished: 0 };
+    const kind = stats.isDirectory() ? 'directory' : 'tarball';
+    let published;
+    if (kind === 'directory') {
+        published = directoryPublishSet(path);
+        walkDirectory(path, path, collector, published);
+    }
+    else {
+        published = TARBALL_PUBLISH_SET;
+        try {
+            await readTarball(path, collector);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new SourceError(`cannot read tarball ${path}: ${detail}`);
+        }
+        if (collector.entries === 0) {
+            throw new SourceError(`${path} holds no tar entries — this is not a readable npm tarball`);
+        }
+    }
+    if (!collector.files.has('package.json')) {
+        throw new SourceError(`no readable package.json in ${path} — this is not an npm package`);
+    }
+    return {
+        kind,
+        path,
+        files: collector.files,
+        skipped: collector.skipped,
+        bytesRead: collector.bytes,
+        publishBasis: published.basis,
+        unpublishedFiles: collector.unpublished,
+    };
+}

package/lib/types/checks/input.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The decoded package every check tier reads from.
+ *
+ * Parsing happens once, in `inspect.ts`, and each tier receives the result.
+ * That keeps the tiers pure functions of already-parsed data — which is what
+ * makes "no analysed code was executed" a property of one small module rather
+ * than something every check has to be trusted about.
+ * @module dsh-plugin-inspector/checks/input
+ */
+import type { PatchDocument, PatchParseError } from '../cordis-yaml.ts';
+import type { PackageManifest } from '../manifest.ts';
+import type { PluginSource } from '../source.ts';
+/** A patch layer that could not be parsed. */
+export interface PatchFailure {
+    /** Package-relative path of the YAML file. */
+    readonly file: string;
+    readonly error: PatchParseError;
+}
+/** Everything the checks see. */
+export interface CheckInput {
+    readonly source: PluginSource;
+    readonly manifest: PackageManifest;
+    /**
+     * True when `package.json` declares `dsh.bundle.patch`. False means nothing
+     * in this package composes into a profile, which forbids every Tier A
+     * patch-row verdict outright — see `runTierA`.
+     */
+    readonly mountsAsBundle: boolean;
+    /**
+     * The mounted patch layer, parsed. At most one: `dsh.bundle.patch` names
+     * exactly one file and the launcher reads no other.
+     */
+    readonly patches: readonly PatchDocument[];
+    readonly patchFailures: readonly PatchFailure[];
+    /** Cordis YAML the package ships but no manifest key mounts. */
+    readonly unmountedPatchFiles: readonly string[];
+    /** Package-relative paths of shipped JavaScript and TypeScript source. */
+    readonly sourceFiles: readonly string[];
+    /** Package-relative paths of shipped skill and agent-instruction markdown. */
+    readonly modelVisibleFiles: readonly string[];
+}
+//# sourceMappingURL=input.d.ts.map

package/lib/types/checks/tier-a.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tier A — decidable checks over structured declarations.
+ *
+ * Everything here reads a field the harness itself must read literally in order
+ * to act on it: a `package.json` key, or a Cordis patch row. That is why Tier A
+ * findings carry `certain` confidence and why they are the only findings this
+ * tool treats as verdicts. `disabled: true` cannot be obfuscated and still
+ * disable anything.
+ * @module dsh-plugin-inspector/checks/tier-a
+ */
+import type { Finding } from '../model.ts';
+import type { CheckInput } from './input.ts';
+/**
+ * Run every Tier A check.
+ *
+ * The filter is the guard: a package that declares no `dsh.bundle.patch`
+ * composes into no profile, so no reading of a Cordis row in it can be a
+ * verdict about anything. `patches` is already empty in that case; this makes
+ * the property structural rather than a consequence of how the input was built.
+ * @param input - the decoded package.
+ * @returns findings, unordered.
+ */
+export declare function runTierA(input: CheckInput): Finding[];
+//# sourceMappingURL=tier-a.d.ts.map

package/lib/types/checks/tier-b.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tier B — capability detection over shipped source.
+ *
+ * Everything here answers "this plugin CAN do X", never "this plugin DOES X".
+ * The distinction is load-bearing for B8: finding a credential read and a
+ * network call in the same package is not evidence that the credential reaches
+ * the socket, and the finding says so.
+ *
+ * Parsing is `ts.createSourceFile` — syntax only. No program is created, no
+ * type checker is instantiated, no module is resolved, nothing is transpiled,
+ * and nothing is executed. Every check is a shape match on one AST node, which
+ * is also why every check has a one-line bypass, carried in the finding.
+ * @module dsh-plugin-inspector/checks/tier-b
+ */
+import type { Finding } from '../model.ts';
+import type { CheckInput } from './input.ts';
+/**
+ * Run every Tier B check.
+ * @param input - the decoded package.
+ * @returns findings, unordered.
+ */
+export declare function runTierB(input: CheckInput): Finding[];
+//# sourceMappingURL=tier-b.d.ts.map

package/lib/types/checks/tier-c.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tier C — how much of the package the analyzer could actually read.
+ *
+ * These checks do not describe the plugin's behavior. They describe the limits
+ * of the analysis, and that is why a Tier C hit is a finding rather than a
+ * silent internal flag: "we cannot read this" is a legitimate result and the
+ * user is entitled to see it.
+ *
+ * A Tier C hit also has a mechanical consequence. Tier B recognises a whitelist
+ * of syntactic shapes, so when code is minified, when identifiers are computed,
+ * or when the shipped artifact has no readable source, a Tier B *positive* is
+ * still true but a Tier B *negative* means nothing. `inspect.ts` reads the
+ * output of this module to lower Tier B confidence and to forbid the report
+ * from claiming nothing was found.
+ * @module dsh-plugin-inspector/checks/tier-c
+ */
+import type { Finding } from '../model.ts';
+import type { CheckInput } from './input.ts';
+/**
+ * Tier C checks that do **not** make a Tier B negative unreliable.
+ *
+ * Every other check here says the analyzer could not read something. C3 says
+ * the opposite: the bytes were read exactly as written and exactly as they will
+ * run — what cannot be checked is whether they match the repository that
+ * claims to have produced them. That is worth reporting and it is not a reason
+ * to distrust the parse, and treating it as one marks every ordinary published
+ * tarball `degraded`, because shipping built output and no source is what
+ * publishing a package *is*.
+ */
+export declare const NON_DEGRADING_CHECKS: ReadonlySet<string>;
+/**
+ * Run every Tier C check.
+ * @param input - the decoded package.
+ * @returns findings, unordered.
+ */
+export declare function runTierC(input: CheckInput): Finding[];
+//# sourceMappingURL=tier-c.d.ts.map

package/lib/types/cli.d.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * `dsh-inspect` — the command line face of the inspector.
+ *
+ * Exit codes are the CI contract and are deliberately three-valued:
+ * `0` clean, `1` findings at or above the threshold, `2` the analysis could not
+ * be performed. A job that cannot tell "the analyzer broke" from "the plugin is
+ * clean" is the failure mode that split exists to prevent.
+ * @module dsh-plugin-inspector/cli
+ */
+import { type Severity } from './model.ts';
+/** Exit codes this tool uses. */
+export declare const EXIT: {
+    readonly clean: 0;
+    readonly findings: 1;
+    readonly unanalysable: 2;
+};
+/** One parsed command line. */
+interface Options {
+    readonly target: string;
+    readonly json: boolean;
+    readonly failOn: Severity | 'none';
+    readonly color: boolean;
+}
+/** Raised for a malformed command line; the message is printed and the tool exits 2. */
+export declare class UsageError extends Error {
+}
+/**
+ * Parse argv.
+ * @param argv - arguments after the node binary and script path.
+ * @returns the parsed options, or `null` when usage or version was requested.
+ * @throws UsageError on an unrecognised or incomplete argument.
+ */
+export declare function parseArgs(argv: readonly string[]): Options | null;
+/**
+ * Run one invocation.
+ * @param argv - arguments after the node binary and script path.
+ * @returns the process exit code.
+ */
+export declare function main(argv: readonly string[]): Promise<number>;
+/**
+ * Report a failure that reached no `try`, and say which exit code it is.
+ *
+ * Not every failure can be caught where it happens. A `RangeError` raised
+ * inside a stream's `'end'` handler is thrown at an EventEmitter, not at the
+ * `await`, so it walks past every `catch` in this program and kills the process
+ * with Node's default handler — which exits **1**, the code that means "the
+ * analysis completed and found something at or above --fail-on". A CI job then
+ * reads a crash as a verdict. The whole point of a separate code 2 is that this
+ * cannot happen, so the last resort has to be covered too.
+ * @param error - whatever was thrown.
+ * @returns the exit code to leave with.
+ */
+export declare function reportFatal(error: unknown): number;
+export {};
+//# sourceMappingURL=cli.d.ts.map