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

package/lib/index.js

@@ -1,12 +1,19 @@
 /**
- * Optional provider plugin for dsh-skill-pack-security.
+ * Provider plugin for dsh-skill-pack-security — "skill 教流程，插件自动执行".
  *
- * Registers one SkillProvider on `ctx.skills` whose candidates are this
- * package's own `skills/` directory, reusing the official
- * `FileSystemSkillProvider` so frontmatter parsing semantics are byte-identical
- * with the built-in local provider (same fail-closed rules, same kebab-case
- * names, same invocation policy). The pack itself works without this plugin —
- * installing it only avoids copying skills into a scanned root.
+ * Registers two capabilities:
+ *  1. a SkillProvider on `ctx.skills` whose candidates are this package's own
+ *     `skills/` directory (reusing the official `FileSystemSkillProvider`, so
+ *     frontmatter parsing semantics are byte-identical with the built-in
+ *     provider), and
+ *  2. the `plugin_vet` supply-chain gate tool on `ctx.tools`: an automated
+ *     pre-install scanner (license / SBOM / commit pinning / malicious
+ *     patterns / five-dimension risk score) whose every finding cites the
+ *     pack skill section to continue as a manual audit.
+ *
+ * The scan engine is zero-dependency (Node built-ins only) and the plugin
+ * injects no prompt paragraphs: the gate lives entirely in the tool result,
+ * keeping the session persona untouched.
  *
  * @module dsh-skill-pack-security/provider
  */
@@ -15,12 +22,27 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem';
 import z from '@deepseek-ai/schemastery';
+import { resolveVetConfig } from './vet/config.js';
+import { buildVetTool } from './vet/tool.js';
 export const name = 'skill-pack-security';
-export const inject = ['skills'];
+export const inject = ['skills', 'tools'];
 export const Config = z.object({
     watch: z.boolean().default(false),
     language: z.union(['zh', 'en']).default('zh'),
     skillsDir: z.string().min(1),
+    vet: z.object({
+        enable: z.boolean().default(true),
+        timeoutMs: z.natural().min(1000).max(300000).default(15000),
+        maxFiles: z.natural().min(1).max(20000).default(800),
+        maxFileBytes: z.natural().min(1024).max(16 * 1024 * 1024).default(256 * 1024),
+        maxExtractBytes: z.natural().min(1024).max(512 * 1024 * 1024).default(64 * 1024 * 1024),
+        maxDepNodes: z.natural().min(1).max(10000).default(600),
+        maxFindingsPerCheck: z.natural().min(1).max(100).default(12),
+        userAgent: z.string().max(200).default('dsh-skill-pack-security/2.0.0 (+https://github.com/PerryLink/dsh-skill-pack-security)'),
+        gate: z.object({
+            policy: z.union(['warn', 'deny']).default('warn'),
+        }),
+    }),
 });
 /** Directory of this module: `provider/src` under tsx or `provider/lib` when built. */
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -79,4 +101,10 @@ export function apply(ctx, config = {}) {
             watch: config.watch ?? false,
         }));
     });
+    const vet = resolveVetConfig(config.vet);
+    if (vet.enable) {
+        ctx.effect(function* () {
+            yield ctx.tools.register(buildVetTool(vet, config.language ?? 'zh'));
+        });
+    }
 }

package/lib/types/index.d.ts

@@ -1,21 +1,31 @@
 /**
- * Optional provider plugin for dsh-skill-pack-security.
+ * Provider plugin for dsh-skill-pack-security — "skill 教流程，插件自动执行".
  *
- * Registers one SkillProvider on `ctx.skills` whose candidates are this
- * package's own `skills/` directory, reusing the official
- * `FileSystemSkillProvider` so frontmatter parsing semantics are byte-identical
- * with the built-in local provider (same fail-closed rules, same kebab-case
- * names, same invocation policy). The pack itself works without this plugin —
- * installing it only avoids copying skills into a scanned root.
+ * Registers two capabilities:
+ *  1. a SkillProvider on `ctx.skills` whose candidates are this package's own
+ *     `skills/` directory (reusing the official `FileSystemSkillProvider`, so
+ *     frontmatter parsing semantics are byte-identical with the built-in
+ *     provider), and
+ *  2. the `plugin_vet` supply-chain gate tool on `ctx.tools`: an automated
+ *     pre-install scanner (license / SBOM / commit pinning / malicious
+ *     patterns / five-dimension risk score) whose every finding cites the
+ *     pack skill section to continue as a manual audit.
+ *
+ * The scan engine is zero-dependency (Node built-ins only) and the plugin
+ * injects no prompt paragraphs: the gate lives entirely in the tool result,
+ * keeping the session persona untouched.
  *
  * @module dsh-skill-pack-security/provider
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type Schema from '@deepseek-ai/schemastery';
+import { type VetConfigInput } from './vet/config.js';
 export declare const name = "skill-pack-security";
 export declare const inject: string[];
-/** The skill language the provider publishes. */
+/** The skill language the provider publishes (and the plugin_vet report language). */
 export type PackLanguage = 'zh' | 'en';
+/** plugin_vet gate policy: warn (default, non-blocking) or deny (blocks install on FAIL). */
+export type GatePolicy = 'warn' | 'deny';
 /** Configuration for the packaged skill provider. */
 export interface Config {
     /** Whether to watch the packaged skills directory; packaged content is static, so default false. */
@@ -24,6 +34,8 @@ export interface Config {
     language?: PackLanguage;
     /** Explicit skills root; overrides the `language`-derived default. Must be a non-empty path to an existing root with `<skill>/SKILL.md` bundles. */
     skillsDir?: string;
+    /** plugin_vet scanner + installation-gate configuration. */
+    vet?: VetConfigInput;
 }
 export declare const Config: Schema<Config>;
 /** Register the packaged skills directory as a custom-root provider. */

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

@@ -0,0 +1,43 @@
+/**
+ * The eight plugin_vet checks. Every function is pure: it reads the shared
+ * inputs and returns one `VetCheck` with redacted, capped findings. No check
+ * touches the network or the filesystem — resolution happened upstream in
+ * `source.ts`.
+ *
+ * @module dsh-skill-pack-security/vet/checks
+ */
+import { type LockData, type Manifest } from './manifest.js';
+import { type GitHubMeta, type NpmMeta, type ResolvedTarget } from './source.js';
+import { type Lang } from './skills.js';
+import type { VetConfig } from './config.js';
+import type { ScannedFile } from './walk.js';
+import type { CheckId, VetCheck, VetSbom } from './vocabulary.js';
+/** Shared inputs every check reads. */
+export interface CheckInputs {
+    readonly files: ScannedFile[];
+    readonly manifest: Manifest;
+    readonly lock: LockData;
+    readonly github: GitHubMeta | null;
+    readonly npm: NpmMeta | null;
+    readonly target: ResolvedTarget;
+    readonly config: VetConfig;
+    readonly lang: Lang;
+    /** 40-hex HEAD of a local git target, when readable without spawning git. */
+    readonly localHead: string;
+    readonly now: number;
+}
+/** One check run: the check plus its optional SBOM payload. */
+export interface CheckResult {
+    readonly check: VetCheck;
+    readonly sbom?: VetSbom;
+}
+export declare function licenseCheck(inputs: CheckInputs): VetCheck;
+export declare function sbomCheck(inputs: CheckInputs): CheckResult;
+export declare function commitLockCheck(inputs: CheckInputs): VetCheck;
+export declare function installScriptsCheck(inputs: CheckInputs): VetCheck;
+export declare function networkExfilCheck(inputs: CheckInputs): VetCheck;
+export declare function obfuscationCheck(inputs: CheckInputs): VetCheck;
+export declare function sourceCheck(inputs: CheckInputs): VetCheck;
+export declare function maintenanceCheck(inputs: CheckInputs): VetCheck;
+/** Run the requested checks over shared inputs. */
+export declare function runChecks(inputs: CheckInputs, ids: readonly CheckId[]): CheckResult[];

package/lib/types/vet/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolved plugin_vet configuration: plain values with defaults applied.
+ *
+ * The Schemastery schema lives in `../index.ts` next to the skills-provider
+ * config; this module only consumes the already-validated plain object so the
+ * engine never depends on Schemastery at runtime.
+ *
+ * @module dsh-skill-pack-security/vet/config
+ */
+import type { GatePolicy } from './vocabulary.js';
+/** Raw config block as validated by the Schemastery schema. */
+export interface VetConfigInput {
+    readonly enable?: boolean;
+    readonly timeoutMs?: number;
+    readonly maxFiles?: number;
+    readonly maxFileBytes?: number;
+    readonly maxExtractBytes?: number;
+    readonly maxDepNodes?: number;
+    readonly maxFindingsPerCheck?: number;
+    readonly userAgent?: string;
+    readonly gate?: {
+        readonly policy?: GatePolicy;
+    };
+}
+/** Fully resolved configuration with defaults applied. */
+export interface VetConfig {
+    readonly enable: boolean;
+    readonly timeoutMs: number;
+    readonly maxFiles: number;
+    readonly maxFileBytes: number;
+    readonly maxExtractBytes: number;
+    readonly maxDepNodes: number;
+    readonly maxFindingsPerCheck: number;
+    readonly userAgent: string;
+    readonly gate: {
+        readonly policy: GatePolicy;
+    };
+}
+export declare const VET_DEFAULTS: VetConfig;
+/** Merge raw config over the defaults (the schema already validated shape/ranges). */
+export declare function resolveVetConfig(raw: VetConfigInput | undefined): VetConfig;

package/lib/types/vet/engine.d.ts

@@ -0,0 +1,24 @@
+/**
+ * plugin_vet engine: resolves a target, runs the eight checks, scores the five
+ * risk dimensions, applies the installation gate, and returns the canonical
+ * report. Pure orchestration — all side effects live in `source.ts`/`fetch.ts`
+ * and every value produced here is JSON-safe and redacted.
+ *
+ * @module dsh-skill-pack-security/vet/engine
+ */
+import { type GatePolicy, type VetReport } from './vocabulary.js';
+import type { VetConfig } from './config.js';
+import { type Lang } from './skills.js';
+/** Engine-level failure: target unusable (not found, offline, budget). */
+export declare class VetTargetError extends Error {
+    constructor(message: string);
+}
+/** Tool argument shape (already JSON-validated by defineTool). */
+export interface VetArgs {
+    readonly target: string;
+    readonly ref?: string;
+    readonly checks?: string[];
+    readonly policy?: 'inherit' | GatePolicy;
+}
+/** Run the whole pipeline for one tool call. */
+export declare function runVet(args: VetArgs, config: VetConfig, lang: Lang, signal: AbortSignal | undefined): Promise<VetReport>;

package/lib/types/vet/fetch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Zero-dependency network access for the scan engine.
+ *
+ * Only `globalThis.fetch` (Node 18+ built-in undici) is used. Every request:
+ *  - honors the caller's AbortSignal AND a cooperative timeout
+ *    (`AbortSignal.any` + `AbortSignal.timeout`), so a hung upstream can never
+ *    stall a session;
+ *  - enforces a hard byte cap while reading the body (stream-counted, no
+ *    unbounded buffering);
+ *  - sends a fixed User-Agent and never attaches credentials.
+ *
+ * @module dsh-skill-pack-security/vet/fetch
+ */
+/** Options shared by all fetch helpers. */
+export interface FetchOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs: number;
+    readonly userAgent: string;
+    /** Hard cap on the response body in bytes; oversized bodies abort early. */
+    readonly maxBytes: number;
+}
+/** A successfully read (possibly truncated) text body. */
+export interface FetchedText {
+    readonly status: number;
+    readonly text: string;
+    readonly truncated: boolean;
+}
+/** A successfully read binary body (kept in memory; capped). */
+export interface FetchedBuffer {
+    readonly status: number;
+    readonly buffer: Uint8Array;
+    readonly truncated: boolean;
+}
+/** A network failure — always surfaced as a check `skip`, never as a finding. */
+export declare class VetFetchError extends Error {
+    readonly kind: 'timeout' | 'aborted' | 'http' | 'network' | 'too-large';
+    constructor(kind: VetFetchError['kind'], message: string);
+}
+/** Fetch a text body with size cap. */
+export declare function fetchText(url: string, options: FetchOptions): Promise<FetchedText>;
+/** Fetch a binary body with size cap (tarballs). */
+export declare function fetchBuffer(url: string, options: FetchOptions): Promise<FetchedBuffer>;

package/lib/types/vet/manifest.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Manifest and lockfile parsing for the SBOM check — pure text/JSON parsing,
+ * zero dependencies. Supports package.json plus pnpm-lock.yaml,
+ * package-lock.json (v1–v3) and yarn.lock (v1); unknown formats are reported
+ * as `unsupported`, never guessed.
+ *
+ * @module dsh-skill-pack-security/vet/manifest
+ */
+import type { ScannedFile } from './walk.js';
+import type { VetPackage } from './vocabulary.js';
+/** Parsed package.json facts the checks consume. */
+export interface Manifest {
+    readonly name: string;
+    readonly version: string;
+    readonly license: string;
+    readonly scripts: Record<string, string>;
+    readonly dependencies: Record<string, string>;
+    readonly devDependencies: Record<string, string>;
+    readonly optionalDependencies: Record<string, string>;
+    readonly peerDependencies: Record<string, string>;
+    readonly repository: string;
+    readonly present: boolean;
+}
+/** One dependency edge inside a lockfile entry: name → raw spec. */
+type DepMap = Record<string, string>;
+/** Parsed lockfile summary. */
+export interface LockData {
+    readonly kind: 'pnpm' | 'npm' | 'yarn' | 'unsupported' | null;
+    readonly lockfile: string | null;
+    readonly lockfileVersion: string;
+    /** name@version → its dependencies (name → spec). */
+    readonly entries: Map<string, DepMap>;
+    /** Whether any integrity/shasum field was seen (pinning signal). */
+    readonly hasIntegrity: boolean;
+}
+/** Find and parse the first supported lockfile in the scan set. */
+export declare function parseLockfile(files: ScannedFile[]): LockData;
+/** Parse package.json when present. */
+export declare function parseManifest(files: ScannedFile[]): Manifest;
+/** Normalize a dependency spec into a bare version when possible. */
+export declare function specVersion(spec: string): string;
+/**
+ * Build the dependency tree: BFS from the manifest's direct dependencies
+ * through lockfile edges, deduped by name@version, depth- and node-capped.
+ */
+export declare function buildDependencyTree(manifest: Manifest, lock: LockData, maxNodes: number): {
+    packages: VetPackage[];
+    truncated: boolean;
+    total: number;
+};
+/** Direct specs that are not exact-version pinned (a supply-chain signal). */
+export declare function unpinnedSpecs(manifest: Manifest): string[];
+export {};

package/lib/types/vet/redact.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Report redaction: no secret-shaped text may ever leave the scan engine.
+ *
+ * Applied to every evidence snippet and finding message before a value enters
+ * the canonical report, mirroring the pack's `secret-scan` redaction rule
+ * (type marker only, never the value). Patterns cover the token families the
+ * `secret-scan` skill documents plus webhook/bot URLs.
+ *
+ * @module dsh-skill-pack-security/vet/redact
+ */
+/** Replace every secret-shaped substring with a type marker. */
+export declare function redact(text: string): string;
+/** Cap a raw snippet and redact it for use as finding evidence. */
+export declare function redactSnippet(text: string, maxChars?: number): string;

package/lib/types/vet/report.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Model-facing renderers for the plugin_vet report: the canonical JSON value
+ * becomes a compact markdown report (render), a pending-call card
+ * (presentCall), and a completed gate card (presentResult). Everything is
+ * pure and capped — no secrets (the engine redacts before this layer), no
+ * unbounded trees.
+ *
+ * @module dsh-skill-pack-security/vet/report
+ */
+import { type Lang } from './skills.js';
+import type { VetReport, VetScores } from './vocabulary.js';
+/** Five-dimension score line. */
+export declare function scoresLine(scores: VetScores, lang: Lang): string;
+/** Render the canonical report as model-facing markdown. */
+export declare function renderReport(report: VetReport, lang: Lang): string;
+/** Short gate summary for the completed card (≤ a few lines). */
+export declare function gateSummary(report: VetReport, lang: Lang): string;

package/lib/types/vet/skills.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Skill cross-references and report-language strings for plugin_vet.
+ *
+ * Every check cites the pack skill (and section) that continues its subject
+ * as a manual audit — "skill 教流程，插件自动执行". Skill names are identical
+ * in the zh/en editions, so the reference is language-neutral.
+ *
+ * @module dsh-skill-pack-security/vet/skills
+ */
+import type { CheckId, Dimension } from './vocabulary.js';
+export type Lang = 'zh' | 'en';
+/** check id → pack skill + section (the manual deep-dive continuation). */
+export declare const SKILL_REF: Record<CheckId, string>;
+/** check id → human-readable check name per language. */
+export declare const CHECK_NAME: Record<Lang, Record<CheckId, string>>;
+/** dimension → label per language. */
+export declare const DIMENSION_LABEL: Record<Lang, Record<Dimension, string>>;
+/** Messages shared by checks and the report renderer. */
+export declare const T: {
+    readonly zh: {
+        readonly pass: '通过';
+        readonly warn: '警告';
+        readonly fail: '失败';
+        readonly skip: '跳过';
+        readonly verdictPass: 'PASS';
+        readonly verdictWarn: 'WARN';
+        readonly verdictFail: 'FAIL';
+        readonly gateDenyTitle: '门禁 DENY：此插件未通过供应链检查，安装已被策略拒绝';
+        readonly gateDenyBody: '请加载 supply-chain-review / dependency-audit 技能人工深审；或由可信维护者修改门禁策略后重试。';
+        readonly gateWarnTitle: '门禁警告：plugin_vet 结果为 FAIL，强烈建议停止安装';
+        readonly gateWarnBody: '默认策略 warn 不阻断。继续安装前请按下方 skill 引用人工深审，确认风险可接受。';
+        readonly followup: '人工深审建议（加载对应技能继续）';
+        readonly budget: '扫描预算';
+        readonly budgetTruncated: '扫描被预算截断：结果不完整';
+        readonly offline: '离线/受限';
+        readonly evidence: '证据';
+    };
+    readonly en: {
+        readonly pass: 'pass';
+        readonly warn: 'warn';
+        readonly fail: 'fail';
+        readonly skip: 'skip';
+        readonly verdictPass: 'PASS';
+        readonly verdictWarn: 'WARN';
+        readonly verdictFail: 'FAIL';
+        readonly gateDenyTitle: 'Gate DENY: this plugin failed the supply-chain checks; installation is blocked by policy';
+        readonly gateDenyBody: 'Load the supply-chain-review / dependency-audit skills for a manual deep-dive, or have a trusted maintainer change the gate policy and retry.';
+        readonly gateWarnTitle: 'Gate warning: plugin_vet returned FAIL — installation is strongly discouraged';
+        readonly gateWarnBody: 'The default policy is warn (non-blocking). Before continuing the install, follow the skill references below for a manual review and confirm the risk is acceptable.';
+        readonly followup: 'Manual deep-dive (load these skills to continue)';
+        readonly budget: 'Scan budget';
+        readonly budgetTruncated: 'Scan truncated by budget: results are incomplete';
+        readonly offline: 'Offline/limited';
+        readonly evidence: 'Evidence';
+    };
+};

package/lib/types/vet/source.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { type ScannedFile, type ScanBudget } from './walk.js';
+import type { VetConfig } from './config.js';
+import type { TargetKind } from './vocabulary.js';
+/** GitHub repo metadata the checks consume (subset of the REST API response). */
+export interface GitHubMeta {
+    readonly exists: boolean;
+    readonly defaultBranch: string;
+    readonly licenseSpdx: string | null;
+    readonly licenseName: string | null;
+    readonly pushedAt: string;
+    readonly createdAt: string;
+    readonly archived: boolean;
+    readonly stars: number;
+    readonly description: string;
+    /** The REST API was rate-limited: timestamps/stars are unavailable (files still scanned). */
+    readonly rateLimited: boolean;
+}
+/** npm registry metadata the checks consume. */
+export interface NpmMeta {
+    readonly exists: boolean;
+    readonly name: string;
+    readonly version: string;
+    readonly license: string;
+    readonly gitHead: string;
+    readonly repository: string;
+    readonly scripts: Record<string, string>;
+    readonly dependencies: Record<string, string>;
+    readonly devDependencies: Record<string, string>;
+    readonly distIntegrity: string;
+    readonly timeModified: string;
+    readonly deprecated: string;
+}
+/** A resolved scan target: files, metadata, and identity. */
+export interface ResolvedTarget {
+    readonly kind: TargetKind;
+    readonly resolved: string;
+    readonly ref: string;
+    readonly files: ScannedFile[];
+    readonly budget: ScanBudget;
+    readonly github: GitHubMeta | null;
+    readonly npm: NpmMeta | null;
+}
+/** Resolve one target string into scan inputs. Never throws for network skips; hard budget violations propagate. */
+export declare function resolveTarget(raw: string, config: VetConfig, signal?: AbortSignal): Promise<ResolvedTarget>;
+/** Whether a ref string is a 40-hex immutable commit. */
+export declare function isCommitRef(ref: string): boolean;

package/lib/types/vet/tar.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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
+ */
+/** Budget caps for one extraction. */
+export interface TarBudget {
+    /** Hard cap on total extracted payload bytes. */
+    readonly maxTotalBytes: number;
+    /** Per-file cap; larger members are dropped and `truncated` is set. */
+    readonly maxFileBytes: number;
+    /** Hard cap on the number of extracted file members. */
+    readonly maxFiles: number;
+}
+/** One extracted member. Directories are implied by file paths. */
+export interface TarEntry {
+    readonly path: string;
+    readonly content: Uint8Array;
+}
+/** Result of one extraction. */
+export interface TarResult {
+    readonly files: Map<string, Uint8Array>;
+    readonly symlinks: Map<string, string>;
+    readonly truncated: boolean;
+    readonly totalBytes: number;
+}
+/** Extract one gzipped ustar archive into an in-memory file map. */
+export declare function extractTarGz(gzipped: Uint8Array, budget: TarBudget): TarResult;

package/lib/types/vet/tool.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 type { VetConfig } from './config.js';
+import type { Lang } from './skills.js';
+/**
+ * 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 declare function buildVetTool(config: VetConfig, lang: Lang): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/types/vet/vocabulary.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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
+ */
+/** The five risk dimensions every report scores. */
+export type Dimension = 'license' | 'source' | 'dependencies' | 'build-scripts' | 'maintenance';
+/** Per-check and overall verdicts. `skip` = the check could not run (offline, budget). */
+export type Verdict = 'pass' | 'warn' | 'fail' | 'skip';
+/** One of the two gate policies. */
+export type GatePolicy = 'warn' | 'deny';
+/** How a scan target is addressed. */
+export type TargetKind = 'github-repo' | 'local-path' | 'npm-package';
+/** Stable check ids; each maps to exactly one dimension and one skill section. */
+export type CheckId = 'license' | 'sbom' | 'commit-lock' | 'install-scripts' | 'network-exfil' | 'obfuscation' | 'source' | 'maintenance';
+export declare const ALL_CHECK_IDS: readonly CheckId[];
+/** Finding severity: fail blocks the check, warn downgrades, info is an observation. */
+export type FindingLevel = 'fail' | 'warn' | 'info';
+/**
+ * One machine-checkable finding. `skill` points at the pack skill (and its
+ * section) that continues the manual audit; `evidence` is a redacted, capped
+ * snippet or fact — never a secret, never a full file body.
+ */
+export interface VetFinding {
+    readonly level: FindingLevel;
+    /** Short human-readable claim, in the report language. */
+    readonly message: string;
+    /** File:line location when known (e.g. `package.json:7` or `README.md:12`). */
+    readonly location?: string;
+    /** Pack skill + section to continue the manual audit, e.g. `supply-chain-review §1`. */
+    readonly skill: string;
+    /** Redacted, capped evidence text (≤ 160 chars per entry). */
+    readonly evidence?: string;
+}
+/** One executed check: verdict, findings, skill pointer, and its 0–100 dimension score. */
+export interface VetCheck {
+    readonly id: CheckId;
+    readonly name: string;
+    readonly verdict: Verdict;
+    /** Why the check was skipped (offline, budget, unsupported target). */
+    readonly skipReason?: string;
+    readonly score: number;
+    /** All findings capped by config.maxFindingsPerCheck (truncated notes the cut). */
+    readonly findings: VetFinding[];
+    readonly truncatedFindings: boolean;
+    /** Primary skill + section for manual deep-dive of this check's subject. */
+    readonly skill: string;
+}
+/** One SBOM tree entry (deduped by name@version). */
+export interface VetPackage {
+    readonly name: string;
+    readonly version: string;
+    /** Depth from the root manifest (0 = direct dependency). */
+    readonly depth: number;
+    /** License string as declared, when the lockfile/manifest carried one. */
+    readonly license?: string;
+    /** Whether the entry came from devDependencies only. */
+    readonly dev: boolean;
+}
+/** SBOM summary produced by the `sbom` check. */
+export interface VetSbom {
+    readonly lockfile: string | null;
+    readonly lockfileVersion?: string;
+    readonly directDependencies: number;
+    readonly directDevDependencies: number;
+    readonly packages: VetPackage[];
+    readonly truncated: boolean;
+    readonly totalPackages: number;
+    /** Direct dependency specs that are not pinned to an exact version. */
+    readonly unpinned: string[];
+}
+/** Scorecard: the five dimensions plus the overall weighted score. */
+export interface VetScores {
+    readonly license: number;
+    readonly source: number;
+    readonly dependencies: number;
+    readonly 'build-scripts': number;
+    readonly maintenance: number;
+    readonly overall: number;
+}
+/** Resolved target metadata recorded in the report. */
+export interface VetTarget {
+    readonly raw: string;
+    readonly kind: TargetKind;
+    /** owner/repo for remote targets, resolved absolute path for local ones. */
+    readonly resolved: string;
+    /** Effective ref for remote targets (branch/tag/commit or npm version). */
+    readonly ref: string;
+}
+/** Gate result: policy applied and whether installation is blocked. */
+export interface VetGate {
+    readonly policy: GatePolicy;
+    readonly applied: boolean;
+    readonly blocked: boolean;
+    /** One-line reason when blocked (deny policy + fail verdict). */
+    readonly reason?: string;
+}
+/** Scan budget facts so truncation is never presented as completeness. */
+export interface VetBudget {
+    readonly filesScanned: number;
+    readonly filesSkipped: number;
+    readonly bytesScanned: number;
+    readonly truncated: boolean;
+    readonly truncatedReason?: string;
+}
+/** The canonical plugin_vet report (validated by the tool output schema). */
+export interface VetReport {
+    readonly kind: 'vet-report';
+    readonly target: VetTarget;
+    readonly fetchedAt: string;
+    readonly checks: VetCheck[];
+    readonly scores: VetScores;
+    readonly verdict: Verdict;
+    readonly gate: VetGate;
+    readonly sbom: VetSbom;
+    readonly budget: VetBudget;
+    /** Skill names worth loading for the manual follow-up audit. */
+    readonly followupSkills: string[];
+}