dsh-vet 0.1.0

package/docs/rules/perm.network-client.md

@@ -0,0 +1,27 @@
+# perm.network-client
+
+Opens network connections.
+
+## What it looks for
+
+Client-side network calls: `http(s).request/get`, `net.connect`,
+`net.createConnection`, `tls.connect`, `dns.lookup/resolve`,
+`dgram.createSocket`, global `fetch`, `new WebSocket()`.
+
+## Severity / confidence policy
+
+- Client calls present, no `"web"` seam declared: **medium / high.**
+- `"web"` declared in `dsh.seams`: **info / high** — expected capability,
+  reported for inventory (the endpoints themselves are listed by
+  `egress.outbound-endpoints`).
+- Network modules imported with no observable client call: **info / high.**
+
+## False positives
+
+Server-only listeners (`http.createServer`) are intentionally not counted.
+Transitive network use inside dependencies is not attributed to the plugin
+here — dependency scanning is the `dep.*` family's business.
+
+## Remediation
+
+Declare the web seam in `dsh.seams`, or drop the network access.

package/docs/rules/perm.seam-mismatch.md

@@ -0,0 +1,34 @@
+# perm.seam-mismatch
+
+Capability used by the plugin's code but not declared in `dsh.seams`.
+
+## What it looks for
+
+Seams are declared in package.json:
+
+```json
+{ "dsh": { "seams": ["fs", "web"] } }
+```
+
+Detected capabilities map to seams: `fs`/`fs-write` → `fs`, `child_process` →
+`shell`, net/http/fetch → `web`, `worker_threads` → `workers`. When a
+declaration exists and a detected capability's seam is missing from it, this
+rule reports the first use site per missing seam.
+
+## Severity / confidence policy
+
+- **medium / medium.** The capability demonstrably exists; the declaration
+  demonstrably omits it. Both are facts; the mismatch is the interpretation.
+- When **no** `dsh.seams` declaration exists at all, this rule stays silent:
+  an absent declaration is not a claim, and per-capability rules
+  (`perm.subprocess-spawn`, `perm.network-client`) speak instead.
+
+## False positives
+
+A plugin that computes its seam set at runtime or documents capabilities in
+README prose only. Dispute with evidence of the declaration and the rule will
+be taught that form.
+
+## Remediation
+
+Add the seam to `dsh.seams`, or drop the capability if it is not needed.

package/docs/rules/perm.subprocess-spawn.md

@@ -0,0 +1,28 @@
+# perm.subprocess-spawn
+
+Spawns subprocesses.
+
+## What it looks for
+
+`child_process` call sites: `spawn`, `exec`, `execFile`, `fork` and their
+`*Sync` variants, reached through any import style (ESM named/default, CJS
+`require`, destructuring).
+
+## Severity / confidence policy
+
+- Spawn call sites present, no `"shell"` seam declared: **medium / high.**
+  The call is a fact; whether it is justified is the reader's call.
+- `"shell"` declared in `dsh.seams`: **info / high** — expected capability,
+  reported for inventory.
+- `child_process` imported but never called: **info / high** (dead import,
+  not an exercised capability).
+
+## False positives
+
+Plugins whose whole purpose is running commands (a shell helper, a runner).
+Declaring the `shell` seam turns the finding into inventory; the honest fix
+is the declaration, not the report's silence.
+
+## Remediation
+
+Declare the shell seam in `dsh.seams`, or avoid spawning processes.

package/docs/rules/perm.undeclared-fs-write.md

@@ -0,0 +1,32 @@
+# perm.undeclared-fs-write
+
+Writes or deletes files outside any plausible plugin scope.
+
+## What it looks for
+
+Calls to write/delete filesystem APIs (`writeFile`, `rm`, `unlink`,
+`truncate`, `rename`, …) in shipped JS. Literal absolute paths **outside** the
+plausible scope — the temp directory and the DSH home subtree
+(`~/.dsh`, `~/.config/dsh`, `~/.cache/dsh`) — are flagged. Relative paths and
+in-scope paths are not.
+
+## Severity / confidence policy
+
+- Destructive APIs (`rm`, `unlink`, `rmdir`, `truncate`) with a literal
+  out-of-scope absolute path: **critical / high** — the spec reserves critical
+  for destructive operations outside any declared scope.
+- Non-destructive writes with a literal out-of-scope absolute path:
+  **high / high.**
+- Writes whose target is a runtime value: **medium / low** (ROADMAP D2 —
+  runtime-dependent findings never lower a grade on their own).
+
+## False positives
+
+A plugin that legitimately manages files elsewhere on disk (a backup tool,
+say). The scope list is deliberately tiny; dispute with the use case and the
+scope list gets a documented entry, not a silent exception.
+
+## Remediation
+
+Keep writes inside the workspace or the DSH home directory; derive paths from
+configuration instead of literals.

package/docs/rules/perm.unreachable-files.md

@@ -0,0 +1,26 @@
+# perm.unreachable-files
+
+Shipped files not reachable from any declared entry point.
+
+## What it looks for
+
+The module graph starts from `main`/`module`/`exports`/`bin` entry points and
+follows static imports and literal `require`/`import()`. Files the graph never
+reaches are listed.
+
+## Severity / confidence policy
+
+**info / high** — never affects a grade. Unreachable is not malicious: dead
+code, fixtures, and dynamic-graph plugins all produce it. It is reported
+because shipped-but-unreachable files can still be `require`d at runtime by
+design or by an attacker, and a reviewer should know they exist.
+
+## False positives
+
+Plugins that build their module graph from config strings at runtime. This is
+the same population as `obf.dynamic-require`; the fix there (plain
+specifiers) fixes the noise here.
+
+## Remediation
+
+Delete dead files or wire them into the import graph.

package/lib/index.d.mts

@@ -0,0 +1,297 @@
+import { existsSync } from "node:fs";
+import { Node } from "acorn";
+//#region src/contract.d.ts
+/**
+ * The `dsh-vet/v1` report contract: a machine-readable, implementation-
+ * agnostic audit report for DeepSeek Harness (DSH) plugins. Any scanner may
+ * emit it; any marketplace, CI job, or UI may consume it. See
+ * `docs/dsh-vet-v1.md` for the normative spec.
+ *
+ * Two design rules are encoded here, not just documented:
+ * - Findings are signals, not verdicts: a finding with `low` confidence never
+ *   lowers a grade, and `info` severity never does either.
+ * - Reports are deterministic: findings are sorted, and the summary is always
+ *   derived, never asserted by the emitter.
+ *
+ * @module dsh-vet/contract
+ */
+/** Literal `schema` value every dsh-vet/v1 report carries. */
+declare const SCHEMA_ID: "dsh-vet/v1";
+/** How bad a finding is. `info` never affects a grade. */
+type VetSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/** How sure the scanner is that the finding is real. `low` never affects a grade. */
+type VetConfidence = 'high' | 'medium' | 'low';
+/** Grade derived from graded findings. `X` marks an incomplete or errored scan. */
+type VetGrade = 'A' | 'B' | 'C' | 'D' | 'F' | 'X';
+interface VetEvidence {
+  /** Path within the audited package, e.g. `host-half.js`. */
+  file: string;
+  /** 1-based line of the evidence, when known. */
+  line?: number;
+  /** Minimal verbatim snippet; never include secrets. */
+  snippet?: string;
+  /** What the evidence shows, one sentence. */
+  note?: string;
+}
+interface VetFinding {
+  /**
+   * Namespaced rule id, e.g. `perm.broad-fs-write` or a vendor-prefixed
+   * `acme.eval-detect`. Must match {@link RULE_ID_PATTERN}; two or more
+   * dot-separated segments so third-party rule sets never collide.
+   */
+  id: string;
+  /** One-line human title, e.g. `Writes outside the declared workspace`. */
+  title: string;
+  severity: VetSeverity;
+  confidence: VetConfidence;
+  evidence: VetEvidence[];
+  /** How to make the finding go away, when actionable. */
+  remediation?: string;
+  /** URLs to rule documentation. */
+  references?: string[];
+}
+type VetTargetKind = 'npm-package' | 'git-repo' | 'local-path';
+interface VetTarget {
+  kind: VetTargetKind;
+  /** What was audited, e.g. `dsh-vault@1.10.6`, a git URL, or a path. */
+  specifier: string;
+  /** What the specifier resolved to, when applicable. */
+  resolved?: {
+    version?: string;
+    commit?: string;
+    /** Subresource integrity of the exact artifact that was scanned. */
+    integrity?: string;
+  };
+}
+interface VetScanner {
+  /** Emitting implementation, e.g. `dsh-vet`. */
+  name: string;
+  version: string;
+  /** RFC 3339 timestamp of the run. */
+  ranAt: string;
+}
+interface VetSummaryCounts {
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  info: number;
+}
+interface VetSummary {
+  grade: VetGrade;
+  counts: VetSummaryCounts;
+}
+interface VetReport {
+  readonly schema: typeof SCHEMA_ID;
+  readonly target: VetTarget;
+  readonly scanner: VetScanner;
+  readonly summary: VetSummary;
+  readonly findings: readonly VetFinding[];
+}
+/**
+ * Rule ids are two or more dot-separated lowercase segments
+ * (`perm.broad-fs-write`, `acme.eval-detect`). Deliberately open-ended about
+ * segment count so vendor-prefixed rule sets work — a closed single-segment
+ * pattern is how the dsh-doctor contract initially broke third-party ids.
+ */
+declare const RULE_ID_PATTERN: RegExp;
+/** True when a finding participates in grading: not `info`, not low-confidence. */
+declare function isGraded(finding: VetFinding): boolean;
+/** Per-severity finding totals. */
+declare function countFindings(findings: readonly VetFinding[]): VetSummaryCounts;
+/**
+ * Derive the grade from graded findings only: worst severity decides.
+ * `low`-confidence and `info` findings are reported but never lower a grade.
+ */
+declare function gradeFor(findings: readonly VetFinding[]): Exclude<VetGrade, 'X'>;
+interface CreateReportInput {
+  target: VetTarget;
+  scanner: VetScanner;
+  findings: readonly VetFinding[];
+}
+/**
+ * Build a normalized report: validates rule ids, sorts findings
+ * deterministically (worst severity first, then id ascending), and derives
+ * the summary. Emitters must go through this instead of assembling a report
+ * by hand — it is what keeps two runs over the same artifact identical.
+ */
+declare function createReport(input: CreateReportInput): VetReport;
+//#endregion
+//#region src/analyze.d.ts
+type Capability = 'fs' | 'fs-write' | 'shell' | 'net' | 'workers' | 'crypto' | 'env' | 'homedir' | 'secret-read';
+interface CapabilityUse {
+  cap: Capability;
+  file: string;
+  line: number;
+  api: string;
+  snippet: string;
+  /** Literal argument strings at the call site, when statically known. */
+  literals: string[];
+}
+interface NetUse {
+  file: string;
+  line: number;
+  api: string;
+  literals: string[];
+  snippet: string;
+}
+interface EvalUse {
+  file: string;
+  line: number;
+  kind: 'eval' | 'Function';
+  literal: boolean;
+  snippet: string;
+}
+interface DynamicImportUse {
+  file: string;
+  line: number;
+  kind: 'require' | 'import';
+  /** Statically concatenated argument value, when recoverable. */
+  literals: string[] | null;
+  snippet: string;
+}
+interface EncodedLiteral {
+  file: string;
+  line: number;
+  value: string;
+  charset: 'base64' | 'hex';
+}
+interface CharcodeCall {
+  file: string;
+  line: number;
+  chars: string;
+}
+interface ImportRef {
+  specifier: string;
+  line: number;
+}
+interface SourceFile {
+  path: string;
+  code: string;
+  sourceType: 'module' | 'script' | null;
+  parseError: string | null;
+  ast: Node | null;
+  imports: ImportRef[];
+  /** Bare (non-relative) module specifiers imported by this file. */
+  externals: string[];
+}
+interface PkgJson {
+  raw: Record<string, unknown>;
+  name: string;
+  version: string;
+  scripts: Record<string, string>;
+  dependencies: Record<string, string>;
+  devDependencies: Record<string, string>;
+  /** Declared Cordis seams, read from `dsh.seams` in package.json. */
+  seams: string[] | null;
+  entryHints: string[];
+}
+interface Analysis {
+  rootDir: string;
+  pkg: PkgJson | null;
+  files: SourceFile[];
+  fileByPath: Map<string, SourceFile>;
+  entries: string[];
+  reachable: Set<string>;
+  unreachable: string[];
+  /** Static relative import edges: file → files it imports. */
+  edges: Map<string, string[]>;
+  capUses: CapabilityUse[];
+  netUses: NetUse[];
+  evalUses: EvalUse[];
+  dynamicImports: DynamicImportUse[];
+  encodedLiterals: EncodedLiteral[];
+  charcodeCalls: CharcodeCall[];
+}
+/** Analyze a package directory: parse, walk, and build the module graph. */
+declare function analyze(rootDir: string): Analysis;
+/** All files statically reachable from `path` (excluding the path itself). */
+declare function reachableFrom(analysis: Analysis, path: string): Set<string>;
+//#endregion
+//#region src/resolve.d.ts
+type SpecifierKind = VetTarget['kind'];
+interface ResolveOptions {
+  /** Injectable fetch for tests; defaults to the global fetch. */
+  fetchImpl?: (url: string) => Promise<Response>;
+  /** Registry base, default `https://registry.npmjs.org`. */
+  registry?: string;
+}
+interface ResolvedTarget {
+  target: VetTarget;
+  /** Local directory holding the artifact to scan. */
+  rootDir: string;
+  /** Package-relative paths of files the tarball contained, when known. */
+  files?: string[];
+  /** Links found in the tarball that were deliberately not materialized. */
+  skippedLinks?: Array<{
+    path: string;
+    type: string;
+    target: string;
+  }>;
+  cleanup: () => void;
+}
+declare class VetError extends Error {}
+/** Classify a specifier without any network access. */
+declare function classifySpecifier(specifier: string, exists?: typeof existsSync): SpecifierKind;
+/** Split `name`, `name@version`, `@scope/name`, `@scope/name@tag|version`. */
+declare function parseNpmSpecifier(specifier: string): {
+  name: string;
+  spec?: string;
+};
+/** Resolve any accepted specifier into a scannable local directory. */
+declare function resolveTarget(specifier: string, opts?: ResolveOptions): Promise<ResolvedTarget>;
+//#endregion
+//#region src/rule.d.ts
+interface RuleContext {
+  analysis: Analysis;
+}
+interface Rule {
+  /** Namespaced id matching RULE_ID_PATTERN, e.g. `perm.subprocess-spawn`. */
+  id: string;
+  /** One-line human title. */
+  title: string;
+  defaultSeverity: VetSeverity;
+  defaultConfidence: VetConfidence;
+  check(ctx: RuleContext): VetFinding[];
+}
+interface FindingInit {
+  title?: string;
+  severity?: VetSeverity;
+  confidence?: VetConfidence;
+  evidence: VetEvidence[];
+  remediation?: string;
+  references?: string[];
+}
+//#endregion
+//#region src/rules/index.d.ts
+declare const RULES: Rule[];
+declare function ruleIds(): string[];
+/** Run all rules, or the subset named in `only` (unknown ids throw). */
+declare function runRules(analysis: Analysis, only?: string[]): VetFinding[];
+//#endregion
+//#region src/scanner.d.ts
+/** Kept in lockstep with package.json; a test asserts they match. */
+declare const SCANNER_VERSION = "0.1.0";
+interface ScanOptions extends ResolveOptions {
+  /** Injectable clock for deterministic tests/reports. */
+  now?: () => string;
+  /** Restrict the scan to these rule ids (CLI `--rules`). */
+  rules?: string[];
+}
+declare function scanDirectory(dir: string, options?: ScanOptions): Promise<VetReport>;
+declare function scan(specifier: string, options?: ScanOptions): Promise<VetReport>;
+//#endregion
+//#region src/cli.d.ts
+/**
+ * CLI (ROADMAP T4). Exit semantics per the dsh-vet/v1 spec: `0` for any
+ * completed report (even a graded-F one), non-zero for scanner failure;
+ * `--strict`/`--fail-on` turn threshold breaches into exit code 1.
+ */
+interface CliIo {
+  stdout: (line: string) => void;
+  stderr: (line: string) => void;
+}
+/** Parse and run; returns the process exit code. */
+declare function runCli(argv: string[], io: CliIo): Promise<number>;
+//#endregion
+export { type Analysis, type Capability, type CapabilityUse, type CharcodeCall, type CliIo, type CreateReportInput, type DynamicImportUse, type EncodedLiteral, type EvalUse, type FindingInit, type ImportRef, type NetUse, type PkgJson, RULES, RULE_ID_PATTERN, type ResolveOptions, type ResolvedTarget, type Rule, type RuleContext, SCANNER_VERSION, SCHEMA_ID, type ScanOptions, type SourceFile, type SpecifierKind, type VetConfidence, VetError, type VetEvidence, type VetFinding, type VetGrade, type VetReport, type VetScanner, type VetSeverity, type VetSummary, type VetSummaryCounts, type VetTarget, type VetTargetKind, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };