@perrylink/dsh-skill-pack-security-provider 2.0.0 → 2.0.1

package/lib/vet/source.js

@@ -0,0 +1,218 @@
+/**
+ * Target resolution: one `plugin_vet` target string becomes either
+ *  - a local directory walk,
+ *  - a GitHub repo (API metadata + codeload tarball, ref-aware), or
+ *  - an npm package (registry metadata + published tarball).
+ *
+ * All remote work flows through the zero-dependency fetch helpers; every
+ * failure is typed so the caller can mark affected checks `skip` instead of
+ * inventing findings.
+ *
+ * @module dsh-skill-pack-security/vet/source
+ */
+import { resolve } from 'node:path';
+import { VetFetchError, fetchBuffer, fetchText } from './fetch.js';
+import { extractTarGz } from './tar.js';
+import { filesFromMap, stripRoot, walkLocal } from './walk.js';
+const GITHUB_RE = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(?:@(.+))?$/;
+const NPM_RE = /^npm:((?:@[^/]+\/)?[^@/]+)@?(.+)$/;
+const HEX40 = /^[0-9a-f]{40}$/i;
+function record(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, spec] of Object.entries(value)) {
+        if (typeof spec === 'string')
+            out[key] = spec;
+    }
+    return out;
+}
+async function githubMeta(owner, repo, config, signal) {
+    const url = `https://api.github.com/repos/${owner}/${repo}`;
+    const empty = {
+        exists: false, defaultBranch: '', licenseSpdx: null, licenseName: null,
+        pushedAt: '', createdAt: '', archived: false, stars: 0, description: '', rateLimited: false,
+    };
+    try {
+        const fetched = await fetchText(url, { signal, timeoutMs: config.timeoutMs, userAgent: config.userAgent, maxBytes: 512 * 1024 });
+        const json = JSON.parse(fetched.text);
+        const license = json['license'];
+        return {
+            exists: true,
+            defaultBranch: typeof json['default_branch'] === 'string' ? json['default_branch'] : 'main',
+            licenseSpdx: typeof license?.['spdx_id'] === 'string' ? license['spdx_id'] : null,
+            licenseName: typeof license?.['name'] === 'string' ? license['name'] : null,
+            pushedAt: typeof json['pushed_at'] === 'string' ? json['pushed_at'] : '',
+            createdAt: typeof json['created_at'] === 'string' ? json['created_at'] : '',
+            archived: json['archived'] === true,
+            stars: typeof json['stargazers_count'] === 'number' ? json['stargazers_count'] : 0,
+            description: typeof json['description'] === 'string' ? json['description'] : '',
+            rateLimited: false,
+        };
+    }
+    catch (error) {
+        if (error instanceof VetFetchError && error.kind === 'http' && error.message.includes('404')) {
+            return empty;
+        }
+        if (error instanceof VetFetchError && error.kind === 'http' && /(403|429)/.test(error.message)) {
+            // Rate-limited: fall back to rate-limit-free endpoints for the tarball
+            // and default branch; timestamps/stars stay unknown.
+            return { ...empty, exists: true, rateLimited: true, defaultBranch: await defaultBranchViaRefs(owner, repo, config, signal) };
+        }
+        throw error;
+    }
+}
+/**
+ * Default-branch discovery without the REST API: the git smart-HTTP refs
+ * advertisement carries `symref=HEAD:refs/heads/<branch>`. No rate limit.
+ */
+async function defaultBranchViaRefs(owner, repo, config, signal) {
+    try {
+        const fetched = await fetchText(`https://github.com/${owner}/${repo}.git/info/refs?service=git-upload-pack`, { signal, timeoutMs: config.timeoutMs, userAgent: 'git/dsh-skill-pack-security', maxBytes: 1024 * 1024 });
+        const symref = /symref=HEAD:refs\/heads\/([^\s]+)/.exec(fetched.text);
+        if (symref !== null)
+            return symref[1];
+        const main = /refs\/heads\/(main|master)\s*$/.exec(fetched.text);
+        if (main !== null)
+            return main[1];
+    }
+    catch {
+        // best effort; caller falls back to 'main'
+    }
+    return 'main';
+}
+function stripPrefix(files, prefix) {
+    if (prefix === '')
+        return files;
+    const out = new Map();
+    for (const [path, content] of files) {
+        if (path.startsWith(`${prefix}/`))
+            out.set(path.slice(prefix.length + 1), content);
+        else
+            out.set(path, content);
+    }
+    return out;
+}
+async function resolveRemote(kind, resolved, ref, tarballUrl, config, signal, github, npm) {
+    let fetched;
+    try {
+        // Tarballs are the slow part of a scan: give them triple the cooperative
+        // timeout while keeping the caller's AbortSignal authoritative.
+        fetched = await fetchBuffer(tarballUrl, {
+            signal, timeoutMs: config.timeoutMs * 3, userAgent: config.userAgent, maxBytes: config.maxExtractBytes,
+        });
+    }
+    catch (error) {
+        if (error instanceof VetFetchError && error.kind === 'http' && error.message.includes('404')) {
+            return { kind, resolved, ref, files: [], budget: { filesScanned: 0, filesSkipped: 0, bytesScanned: 0, truncated: false, truncatedReason: `tarball not found for ${resolved}@${ref}` }, github, npm };
+        }
+        throw error;
+    }
+    const extracted = extractTarGz(fetched.buffer, {
+        maxTotalBytes: config.maxExtractBytes,
+        maxFileBytes: config.maxFileBytes,
+        maxFiles: config.maxFiles,
+    });
+    const root = stripRoot(extracted.files);
+    const stripped = stripPrefix(extracted.files, root);
+    const { files, budget } = filesFromMap(stripped, config.maxFileBytes);
+    if (extracted.truncated && budget.truncatedReason === undefined) {
+        budget.truncated = true;
+        budget.truncatedReason = 'tarball extraction hit the byte/file budget';
+    }
+    return { kind, resolved, ref, files, budget, github, npm };
+}
+async function npmMeta(name, version, config, signal) {
+    const escaped = name.startsWith('@') ? name.replace('/', '%2F') : name;
+    const url = `https://registry.npmjs.org/${escaped}/${version}`;
+    const empty = {
+        exists: false, name, version, license: '', gitHead: '', repository: '',
+        scripts: {}, dependencies: {}, devDependencies: {}, distIntegrity: '', timeModified: '', deprecated: '',
+    };
+    try {
+        const fetched = await fetchText(url, { signal, timeoutMs: config.timeoutMs, userAgent: config.userAgent, maxBytes: 8 * 1024 * 1024 });
+        const json = JSON.parse(fetched.text);
+        const repository = json['repository'];
+        let repositoryString = '';
+        if (typeof repository === 'string')
+            repositoryString = repository;
+        else if (typeof repository === 'object' && repository !== null && !Array.isArray(repository)) {
+            const repoUrl = repository['url'];
+            if (typeof repoUrl === 'string')
+                repositoryString = repoUrl;
+        }
+        const dist = json['dist'];
+        const license = json['license'];
+        let licenseString = '';
+        if (typeof license === 'string')
+            licenseString = license;
+        else if (typeof license === 'object' && license !== null && !Array.isArray(license)) {
+            const type = license['type'];
+            if (typeof type === 'string')
+                licenseString = type;
+        }
+        return {
+            exists: true,
+            name: typeof json['name'] === 'string' ? json['name'] : name,
+            version: typeof json['version'] === 'string' ? json['version'] : version,
+            license: licenseString,
+            gitHead: typeof json['gitHead'] === 'string' ? json['gitHead'] : '',
+            repository: repositoryString,
+            scripts: record(json['scripts']),
+            dependencies: record(json['dependencies']),
+            devDependencies: record(json['devDependencies']),
+            distIntegrity: typeof dist?.['integrity'] === 'string' ? dist['integrity'] : '',
+            timeModified: '',
+            deprecated: '',
+        };
+    }
+    catch (error) {
+        if (error instanceof VetFetchError && error.kind === 'http' && error.message.includes('404'))
+            return empty;
+        throw error;
+    }
+}
+/** Resolve one target string into scan inputs. Never throws for network skips; hard budget violations propagate. */
+export async function resolveTarget(raw, config, signal) {
+    const trimmed = raw.trim();
+    const npmMatch = NPM_RE.exec(trimmed);
+    if (npmMatch !== null) {
+        const name = npmMatch[1];
+        const version = npmMatch[2];
+        const meta = await npmMeta(name, version, config, signal);
+        if (!meta.exists) {
+            return {
+                kind: 'npm-package', resolved: `${name}@${version}`, ref: version, files: [],
+                budget: { filesScanned: 0, filesSkipped: 0, bytesScanned: 0, truncated: false, truncatedReason: 'package not found on the npm registry' },
+                github: null, npm: meta,
+            };
+        }
+        const escaped = name.startsWith('@') ? name.replace('/', '%2F') : name;
+        const tarball = `https://registry.npmjs.org/${escaped}/-/${name.split('/').pop()}-${version}.tgz`;
+        return resolveRemote('npm-package', `${name}@${version}`, version, tarball, config, signal, null, meta);
+    }
+    const githubMatch = GITHUB_RE.exec(trimmed);
+    if (githubMatch !== null) {
+        const owner = githubMatch[1];
+        const repo = githubMatch[2];
+        const meta = await githubMeta(owner, repo, config, signal);
+        if (!meta.exists) {
+            return {
+                kind: 'github-repo', resolved: `${owner}/${repo}`, ref: githubMatch[3] ?? '', files: [],
+                budget: { filesScanned: 0, filesSkipped: 0, bytesScanned: 0, truncated: false, truncatedReason: 'repository not found on GitHub' },
+                github: meta, npm: null,
+            };
+        }
+        const ref = githubMatch[3] ?? meta.defaultBranch;
+        const tarball = `https://codeload.github.com/${owner}/${repo}/tar.gz/${ref}`;
+        return resolveRemote('github-repo', `${owner}/${repo}`, ref, tarball, config, signal, meta, null);
+    }
+    // Local path fallback: relative paths resolve against the process cwd.
+    const abs = resolve(trimmed);
+    const { files, budget } = await walkLocal(abs, config.maxFiles, config.maxFileBytes);
+    return { kind: 'local-path', resolved: abs, ref: '', files, budget, github: null, npm: null };
+}
+/** Whether a ref string is a 40-hex immutable commit. */
+export function isCommitRef(ref) {
+    return HEX40.test(ref.trim());
+}

package/lib/vet/tar.js

@@ -0,0 +1,137 @@
+/**
+ * Minimal gzip + ustar (POSIX tar) extractor — zero dependencies.
+ *
+ * Only the pieces needed to unpack registry/codeload tarballs: regular files,
+ * directories, symlinks (recorded, never followed), GNU long-name (`L`) and
+ * pax (`x`/`g`) extended headers. Hard constraints:
+ *  - path traversal is rejected (absolute paths, `..`, drive letters);
+ *  - total bytes, per-file bytes, and file count are capped;
+ *  - symlink targets are stored as strings only (never materialized).
+ *
+ * @module dsh-skill-pack-security/vet/tar
+ */
+import { gunzipSync } from 'node:zlib';
+class TarError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TarError';
+    }
+}
+const BLOCK = 512;
+/** Decode an ASCII/UTF-8 field, trimming NULs and spaces. */
+function field(buffer, start, length) {
+    let end = start + length;
+    while (end > start && (buffer[end - 1] === 0x00 || buffer[end - 1] === 0x20))
+        end -= 1;
+    return new TextDecoder().decode(buffer.subarray(start, end));
+}
+/** Parse a zero-padded octal size field. */
+function octalSize(buffer, start, length) {
+    const raw = field(buffer, start, length);
+    const clean = raw.replace(/\0/g, '').trim();
+    const value = /^[0-7]+$/.test(clean) ? Number.parseInt(clean, 8) : NaN;
+    return Number.isFinite(value) && value >= 0 ? value : 0;
+}
+/** Reject traversal/absolute/Windows-drive paths before they enter the map. */
+function safePath(path) {
+    if (path.includes('\0'))
+        throw new TarError('tar entry path contains NUL');
+    const normalized = path.replaceAll('\\', '/');
+    const segments = normalized.split('/');
+    for (const segment of segments) {
+        if (segment === '..' || segment === '')
+            continue;
+        if (/^[A-Za-z]:$/.test(segment))
+            throw new TarError(`tar entry escapes with a drive letter: ${path}`);
+    }
+    if (segments.includes('..'))
+        throw new TarError(`tar entry path escapes the root: ${path}`);
+    if (normalized.startsWith('/'))
+        throw new TarError(`tar entry uses an absolute path: ${path}`);
+    return normalized;
+}
+/** Extract one gzipped ustar archive into an in-memory file map. */
+export function extractTarGz(gzipped, budget) {
+    let raw;
+    try {
+        raw = gunzipSync(gzipped);
+    }
+    catch (error) {
+        throw new TarError(`not a gzip stream: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const files = new Map();
+    const symlinks = new Map();
+    let truncated = false;
+    let totalBytes = 0;
+    let offset = 0;
+    let pendingName;
+    let seenEnd = false;
+    while (offset + BLOCK <= raw.length) {
+        const header = raw.subarray(offset, offset + BLOCK);
+        if (header.every(byte => byte === 0)) {
+            // Two consecutive zero blocks end the archive.
+            const next = raw.subarray(offset + BLOCK, offset + 2 * BLOCK);
+            if (next.length === 0 || next.every(byte => byte === 0)) {
+                seenEnd = true;
+                break;
+            }
+        }
+        const nameField = field(header, 0, 100);
+        const size = octalSize(header, 124, 12);
+        const typeflag = String.fromCharCode(header[156] ?? 0);
+        const linkname = field(header, 157, 100);
+        offset += BLOCK;
+        if (typeflag === 'L') {
+            // GNU long name: the payload of this entry is the real path.
+            if (size > 1024 * 1024)
+                throw new TarError('oversized long-name entry');
+            const body = raw.subarray(offset, offset + size);
+            pendingName = new TextDecoder().decode(body).replaceAll('\0', '').trim();
+            offset += Math.ceil(size / BLOCK) * BLOCK;
+            continue;
+        }
+        if (typeflag === 'x' || typeflag === 'g') {
+            // pax extended header: only "path=" matters to us.
+            const body = new TextDecoder().decode(raw.subarray(offset, offset + size));
+            const pathMatch = /(?:^|\n)\d+ path=([^\n]+)/.exec(body);
+            if (pathMatch !== null)
+                pendingName = pathMatch[1];
+            offset += Math.ceil(size / BLOCK) * BLOCK;
+            continue;
+        }
+        if (typeflag !== '0' && typeflag !== '\0' && typeflag !== '5' && typeflag !== '2') {
+            // Device nodes, fifos, hard links, sparse files, etc. — skip payload.
+            offset += Math.ceil(size / BLOCK) * BLOCK;
+            continue;
+        }
+        const path = safePath(pendingName ?? nameField);
+        pendingName = undefined;
+        if (typeflag === '2') {
+            symlinks.set(path, linkname);
+            offset += Math.ceil(size / BLOCK) * BLOCK;
+            continue;
+        }
+        if (typeflag === '5') {
+            // Directory entry: no payload to store.
+            offset += Math.ceil(size / BLOCK) * BLOCK;
+            continue;
+        }
+        if (size > budget.maxFileBytes) {
+            truncated = true;
+            offset += Math.ceil(size / BLOCK) * BLOCK;
+            continue;
+        }
+        if (totalBytes + size > budget.maxTotalBytes || files.size >= budget.maxFiles) {
+            truncated = true;
+            offset += Math.ceil(size / BLOCK) * BLOCK;
+            continue;
+        }
+        const content = raw.subarray(offset, offset + size);
+        files.set(path, content);
+        totalBytes += size;
+        offset += Math.ceil(size / BLOCK) * BLOCK;
+    }
+    if (!seenEnd)
+        throw new TarError('archive ended prematurely (truncated tar stream)');
+    return { files, symlinks, truncated, totalBytes };
+}

package/lib/vet/tool.js

@@ -0,0 +1,164 @@
+/**
+ * The `plugin_vet` tool definition: schema-validated arguments, a strictly
+ * validated canonical report, a model-facing markdown render, and the
+ * pending/completed UI cards. This is the only module in the vet engine that
+ * imports harness packages; everything below it is plain zero-dependency code.
+ *
+ * @module dsh-skill-pack-security/vet/tool
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { runVet } from './engine.js';
+import { renderReport } from './report.js';
+/** Output-side JSON Schema dialect entry for one finding. */
+const FINDING_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        level: { type: 'string', required: true, enum: ['fail', 'warn', 'info'] },
+        message: { type: 'string', required: true },
+        location: { type: 'string' },
+        skill: { type: 'string', required: true },
+        evidence: { type: 'string' },
+    },
+};
+const CHECK_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        id: { type: 'string', required: true },
+        name: { type: 'string', required: true },
+        verdict: { type: 'string', required: true, enum: ['pass', 'warn', 'fail', 'skip'] },
+        skipReason: { type: 'string' },
+        score: { type: 'integer', required: true },
+        findings: { type: 'array', required: true, items: FINDING_SCHEMA },
+        truncatedFindings: { type: 'boolean', required: true },
+        skill: { type: 'string', required: true },
+    },
+};
+const REPORT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        kind: { type: 'string', required: true, const: 'vet-report' },
+        target: {
+            type: 'object', required: true, additionalProperties: false,
+            properties: {
+                raw: { type: 'string', required: true },
+                kind: { type: 'string', required: true, enum: ['github-repo', 'local-path', 'npm-package'] },
+                resolved: { type: 'string', required: true },
+                ref: { type: 'string', required: true },
+            },
+        },
+        fetchedAt: { type: 'string', required: true },
+        checks: { type: 'array', required: true, items: CHECK_SCHEMA },
+        scores: {
+            type: 'object', required: true, additionalProperties: false,
+            properties: {
+                license: { type: 'integer', required: true },
+                source: { type: 'integer', required: true },
+                dependencies: { type: 'integer', required: true },
+                'build-scripts': { type: 'integer', required: true },
+                maintenance: { type: 'integer', required: true },
+                overall: { type: 'integer', required: true },
+            },
+        },
+        verdict: { type: 'string', required: true, enum: ['pass', 'warn', 'fail', 'skip'] },
+        gate: {
+            type: 'object', required: true, additionalProperties: false,
+            properties: {
+                policy: { type: 'string', required: true, enum: ['warn', 'deny'] },
+                applied: { type: 'boolean', required: true },
+                blocked: { type: 'boolean', required: true },
+                reason: { type: 'string' },
+            },
+        },
+        sbom: {
+            type: 'object', required: true, additionalProperties: false,
+            properties: {
+                lockfile: { oneOf: [{ type: 'string' }, { type: 'null' }], required: true },
+                lockfileVersion: { type: 'string' },
+                directDependencies: { type: 'integer', required: true },
+                directDevDependencies: { type: 'integer', required: true },
+                packages: {
+                    type: 'array', required: true,
+                    items: {
+                        type: 'object', additionalProperties: false,
+                        properties: {
+                            name: { type: 'string', required: true },
+                            version: { type: 'string', required: true },
+                            depth: { type: 'integer', required: true },
+                            license: { type: 'string' },
+                            dev: { type: 'boolean', required: true },
+                        },
+                    },
+                },
+                truncated: { type: 'boolean', required: true },
+                totalPackages: { type: 'integer', required: true },
+                unpinned: { type: 'array', required: true, items: { type: 'string' } },
+            },
+        },
+        budget: {
+            type: 'object', required: true, additionalProperties: false,
+            properties: {
+                filesScanned: { type: 'integer', required: true },
+                filesSkipped: { type: 'integer', required: true },
+                bytesScanned: { type: 'integer', required: true },
+                truncated: { type: 'boolean', required: true },
+                truncatedReason: { type: 'string' },
+            },
+        },
+        followupSkills: { type: 'array', required: true, items: { type: 'string' } },
+    },
+};
+function textBlock(text) {
+    return { type: 'text', text };
+}
+/**
+ * Build the plugin_vet tool bound to the resolved plugin configuration.
+ * @param config - resolved vet configuration (defaults already applied).
+ * @param lang - report language, driven by the plugin's `language` config.
+ */
+export function buildVetTool(config, lang) {
+    return defineTool({
+        name: 'plugin_vet',
+        description: 'Supply-chain security gate for DSH plugin repositories/packages. Scans a target (GitHub `owner/repo[@ref]`, an `npm:name@version` package, or a local path) and returns a five-dimension risk report: license, source, dependencies, build scripts, maintenance. Checks: LICENSE/SPDX detection (missing/unknown/NOASSERTION flagged), SBOM dependency tree, 40-hex commit pinning of install references, dangerous postinstall/preinstall scripts, network-exfiltration domains, obfuscated code, source trust signals, maintenance status. Each finding cites the matching dsh-skill-pack-security skill section for a manual deep-dive. Use it BEFORE installing any plugin (`dsh plugin add`); a FAIL verdict warns or blocks depending on the configured gate policy (default warn). Read-only: never modifies the target. Respects timeouts; bounded network use.',
+        parameters: {
+            target: {
+                type: 'string',
+                required: true,
+                description: 'Target to vet: GitHub `owner/repo` or `owner/repo@ref`, npm package `npm:name@version`, or a local absolute/relative path.',
+            },
+            ref: {
+                type: 'string',
+                description: 'Optional git ref override for GitHub targets (prefer a 40-hex commit). Defaults to the repository default branch.',
+            },
+            checks: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional subset of check ids: license, sbom, commit-lock, install-scripts, network-exfil, obfuscation, source, maintenance. Default: all.',
+            },
+            policy: {
+                type: 'string',
+                enum: ['inherit', 'warn', 'deny'],
+                description: 'Per-call gate policy override. inherit (default) uses the configured gate.policy; deny blocks installation on FAIL.',
+            },
+        },
+        output: {
+            schema: REPORT_SCHEMA,
+            render: (_args, value) => [textBlock(renderReport(value, lang))],
+        },
+        timeoutMs: Math.max(config.timeoutMs * 4 + 5000, 30000),
+        async execute(args, exec) {
+            return await runVet({ target: args.target, ref: args.ref, checks: args.checks, policy: args.policy }, config, lang, exec.signal);
+        },
+        presentCall(args) {
+            return { card: 'generic', kind: 'search', title: `plugin_vet ${args.target}`, rawInput: { target: args.target } };
+        },
+        presentResult(args, result) {
+            const content = result.content;
+            const firstText = content.find(block => block.type === 'text');
+            const verdict = /Verdict:\s*(\w+)/.exec(firstText?.text ?? '')?.[1]?.toUpperCase() ?? 'done';
+            return { card: 'generic', title: `plugin_vet ${args.target}: ${verdict}`, content };
+        },
+    });
+}

package/lib/vet/vocabulary.js

@@ -0,0 +1,19 @@
+/**
+ * Shared vocabulary for the plugin_vet supply-chain gate.
+ *
+ * Everything here is plain data (JSON-safe, no live runtime objects) so the
+ * scan engine stays a pure, harness-free module: the tool definition in
+ * `tool.ts` is the only part that touches ctx/defineTool.
+ *
+ * @module dsh-skill-pack-security/vet/vocabulary
+ */
+export const ALL_CHECK_IDS = [
+    'license',
+    'sbom',
+    'commit-lock',
+    'install-scripts',
+    'network-exfil',
+    'obfuscation',
+    'source',
+    'maintenance',
+];