ai-install-guard 0.0.0 → 0.2.0

package/hooks/scan/scan.ts

@@ -0,0 +1,360 @@
+import { codeChecks } from './checks/code'
+import { buildContext, isRecord, parseJson, type CandidateKind, type ScanContext } from './checks/context'
+import { hookChecks } from './checks/hooks'
+import { mcpChecks } from './checks/mcp'
+import { modChecks } from './checks/mod'
+import { promptChecks } from './checks/prompts'
+import { badgeClaim, badgeRow, marketplacePinsCheck, type BadgeClaim } from './checks/provenance'
+import { licenseCheck, qualityChecks } from './checks/quality'
+import { secretChecks } from './checks/secrets'
+import { structureChecks } from './checks/structure'
+import { joinPath } from './checks/text'
+import { GROUPS, rankOf, row, type CheckResult, type Evidence } from './checks/types'
+import { runValidator } from './checks/validator'
+import type { Host } from './host'
+import { treeHash } from './hash'
+import { ScanError, takeInventory, type Inventory, type InventoryEntry, type ScannedTree } from './inventory'
+import { githubProvenance } from './github'
+import { newLookupCache, outsideLookups, type LookupCache } from './lookups'
+import { fetchPinned, type PinnedSource, type RemoteSpec } from './remote'
+import { decide, type Verdict } from './verdict'
+
+export type ScanReport = {
+  /** What was asked for, as the person wrote it. */
+  target: string
+  kind?: CandidateKind
+  inventory?: Inventory
+  results: CheckResult[]
+  verdict: Verdict
+  /** For a remote scan: the one commit that was fetched and checked. */
+  source?: PinnedSource
+  /** What an AI Install Guard badge in the README claims, judged in `results`. */
+  badgeClaim?: BadgeClaim
+}
+
+export type ScanOptions = {
+  /** Run `claude plugin validate` on the candidate (on by default). */
+  validate?: boolean
+  /** The outside lookups (OSV, the official plugin list): off unless turned on. */
+  lookups?: boolean
+  /** Shared by one scan's lookups, so a marketplace and its plugins ask once. */
+  lookupCache?: LookupCache
+  /** Told each stage as it starts, for progress in the pane. */
+  onStage?: (stage: string) => Promise<void> | void
+  /**
+   * Rows from analyzers outside the deterministic checks (the model review, an
+   * add-on). They are added to the report; they can raise the verdict and
+   * never lower it, because a row can only add a WARN or FAIL of its own.
+   */
+  extraResults?: (report: Omit<ScanReport, 'verdict'>) => Promise<CheckResult[]>
+}
+
+/** Scans a local folder: inventory, every deterministic check, the verdict. */
+export async function scanFolder(host: Host, target: string, path: string, rawOptions: ScanOptions = {}): Promise<ScanReport> {
+  // Progress is a courtesy: a failure to show it never fails the scan.
+  const options: ScanOptions = {
+    ...rawOptions,
+    ...(rawOptions.lookups === true && rawOptions.lookupCache === undefined ? { lookupCache: newLookupCache() } : {}),
+    onStage: async stage => {
+      try {
+        await rawOptions.onStage?.(stage)
+      } catch {
+        // ignored on purpose
+      }
+    },
+  }
+  let tree: ScannedTree
+  try {
+    await options.onStage?.('reading files')
+    tree = await takeInventory(host, path)
+  } catch (error) {
+    return { target, results: [], verdict: decide([], reasonOf(error)) }
+  }
+  const ctx = buildContext(tree)
+  let results: CheckResult[]
+  try {
+    await options.onStage?.('running the checks')
+    results = await checksFor(host, ctx, options)
+    // A marketplace's local plugins are plugins in their own right: each is
+    // checked from its own folder, as Claude Code would read it.
+    for (const source of marketplaceSources(ctx)) {
+      if (source.kind === 'overflow') {
+        results = mergeResults(results, [overflowRow(source.count)])
+        continue
+      }
+      if (source.kind === 'remote') {
+        results = mergeResults(results, [remoteSourceNote(source.name, source.description)])
+        continue
+      }
+      await options.onStage?.(`checking ${source.name}`)
+      const nested = await subTree(tree, source.path)
+      if (nested === undefined) {
+        results = mergeResults(results, [missingSourceRow(source.name, source.path)])
+        continue
+      }
+      // A listed plugin's own README badge is judged against its own rows.
+      const nestedCtx = buildContext(nested)
+      const nestedResults = withBadgeClaim(await checksFor(host, nestedCtx, options), badgeClaim(nestedCtx.readme), { treeHash: nested.inventory.treeHash })
+      results = mergeResults(results, prefixed(nestedResults, source.path))
+    }
+  } catch (error) {
+    return { target, kind: ctx.kind, inventory: tree.inventory, results: [], verdict: decide([], `a check failed: ${reasonOf(error)}`) }
+  }
+  if (options.extraResults !== undefined) {
+    const extra = await options
+      .extraResults({ target, kind: ctx.kind, inventory: tree.inventory, results })
+      .catch((error: unknown): CheckResult[] => [
+        {
+          id: 'analysis.unfinished',
+          group: 'quality',
+          title: 'An additional review did not finish',
+          status: 'warn',
+          severity: 'medium',
+          evidence: [{ file: '-', excerpt: reasonOf(error), status: 'warn' }],
+          advice: 'Part of the review you asked for is missing, so the verdict rests on the deterministic checks alone.',
+        },
+      ])
+    results = [...results, ...extra]
+  }
+  const claim = badgeClaim(ctx.readme)
+  results = withBadgeClaim(sortResults(results), claim, { treeHash: tree.inventory.treeHash })
+  return { target, kind: ctx.kind, inventory: tree.inventory, results, verdict: decide(results), ...(claim === undefined ? {} : { badgeClaim: claim }) }
+}
+
+/**
+ * The results with a README badge judged against everything else: the badge
+ * row is computed last, from the verdict the other rows give, so a badge can
+ * add a warning and never lift a verdict.
+ */
+export function withBadgeClaim(results: readonly CheckResult[], claim: BadgeClaim | undefined, version: { sha?: string; treeHash?: string }): CheckResult[] {
+  if (claim === undefined) return [...results]
+  // Evidence about nested plugins' badges, merged in already, stays; this
+  // README's own is judged again.
+  const rest = results.flatMap(result => {
+    if (result.id !== 'provenance.badge') return [result]
+    const kept = result.evidence.filter(item => item.file !== claim.file)
+    return kept.length === 0 ? [] : [row({ id: result.id, group: result.group, title: result.title, advice: result.advice, summary: result.summary }, kept, 'info')]
+  })
+  return sortResults(mergeResults(rest, [badgeRow(claim, decide(rest).kind, version)]))
+}
+
+async function checksFor(host: Host, ctx: ScanContext, options: ScanOptions): Promise<CheckResult[]> {
+  // Claude Code validates plugins and marketplaces; a standalone skill or a
+  // plain folder has no manifest for it to read.
+  const hasManifest = ctx.files.some(file => file.path === '.claude-plugin/plugin.json' || file.path === '.claude-plugin/marketplace.json')
+  const validator = options.validate === false || ctx.kind === 'folder' || (ctx.kind === 'skill' && !hasManifest) ? undefined : await runValidator(host, ctx.tree.inventory.root)
+  return [
+    licenseCheck(ctx),
+    ...marketplacePinsCheck(ctx),
+    ...structureChecks(ctx, validator),
+    ...modChecks(ctx, validator),
+    ...hookChecks(ctx),
+    ...mcpChecks(ctx),
+    ...(options.lookups === true ? await outsideLookups(host, ctx, options.lookupCache) : []),
+    ...promptChecks(ctx),
+    ...codeChecks(ctx),
+    ...secretChecks(ctx),
+    ...qualityChecks(ctx),
+  ]
+}
+
+const MAX_NESTED_PLUGINS = 50
+
+type MarketplaceSource =
+  | { kind: 'local'; name: string; path: string }
+  | { kind: 'remote'; name: string; description: string }
+  | { kind: 'overflow'; count: number }
+
+/** The plugins a `.claude-plugin/marketplace.json` lists, other than the root itself. */
+/**
+ * Scans a remote source: fetches the one commit its ref names into the
+ * guard's own temporary folder, scans that folder, and removes it. A failure
+ * to fetch or verify is "Could not verify", never a pass.
+ */
+export async function scanRemote(host: Host, target: string, spec: RemoteSpec, options: ScanOptions = {}): Promise<ScanReport> {
+  let fetched
+  try {
+    fetched = await fetchPinned(host, spec, async stage => {
+      try {
+        await options.onStage?.(stage)
+      } catch {
+        // Progress is a courtesy, as in scanFolder.
+      }
+    })
+  } catch (error) {
+    return { target, results: [], verdict: decide([], reasonOf(error)) }
+  }
+  try {
+    const report = await scanFolder(host, target, fetched.root, options)
+    if (report.verdict.kind === 'unverified') return { ...report, source: fetched.source }
+    // What GitHub says about where it came from, then the badge, judged again
+    // with the source's own rows counted.
+    // Progress is a courtesy here too: a failure to show it, thrown or
+    // rejected, never fails the scan.
+    try {
+      await options.onStage?.('reading the repository history')
+    } catch {
+      // ignored on purpose
+    }
+    const history = await githubProvenance(host, fetched.source)
+    const results = withBadgeClaim(sortResults([...fetched.results, ...history, ...report.results]), report.badgeClaim, { sha: fetched.source.sha, treeHash: report.inventory?.treeHash })
+    return { ...report, source: fetched.source, results, verdict: decide(results) }
+  } finally {
+    await fetched.cleanup().catch(() => undefined)
+  }
+}
+
+function marketplaceSources(ctx: ScanContext): MarketplaceSource[] {
+  const raw = ctx.text('.claude-plugin/marketplace.json')
+  const parsed = parseJson(raw)
+  if (!parsed.ok || !isRecord(parsed.value) || !Array.isArray(parsed.value.plugins)) return []
+  const out: MarketplaceSource[] = []
+  const skipped = parsed.value.plugins.length - MAX_NESTED_PLUGINS
+  if (skipped > 0) out.push({ kind: 'overflow', count: skipped })
+  for (const plugin of parsed.value.plugins.slice(0, MAX_NESTED_PLUGINS)) {
+    if (!isRecord(plugin)) continue
+    const name = typeof plugin.name === 'string' ? plugin.name : '(unnamed)'
+    const source = plugin.source
+    if (typeof source === 'string' && (source.startsWith('./') || source.startsWith('../'))) {
+      const path = joinPath('', source)
+      if (path === undefined) out.push({ kind: 'remote', name, description: `${source}, outside the marketplace folder` })
+      else if (path !== '') out.push({ kind: 'local', name, path })
+    } else {
+      out.push({ kind: 'remote', name, description: typeof source === 'string' ? source : JSON.stringify(source) })
+    }
+  }
+  return out
+}
+
+/** The part of a scanned tree under `prefix`, re-rooted there. */
+async function subTree(tree: ScannedTree, prefix: string): Promise<ScannedTree | undefined> {
+  const root = `${tree.inventory.root}/${prefix}`
+  const entries = tree.inventory.entries
+    .filter(entry => entry.path.startsWith(`${prefix}/`))
+    .map((entry): InventoryEntry => {
+      const path = entry.path.slice(prefix.length + 1)
+      if (entry.kind !== 'link' || !entry.isInside || entry.landsAt === undefined) return { ...entry, path }
+      // A link's landing, seen from the nested plugin: inside it, or outside
+      // it (once installed on its own, the plugin no longer holds that file).
+      if (entry.landsAt === prefix) return { ...entry, path, landsAt: '.' }
+      return entry.landsAt.startsWith(`${prefix}/`)
+        ? { ...entry, path, landsAt: entry.landsAt.slice(prefix.length + 1) }
+        : { ...entry, path, landsAt: `${tree.inventory.root}/${entry.landsAt}`, isInside: false }
+    })
+  if (entries.length === 0) return undefined
+  const contents = new Map<string, Uint8Array>()
+  for (const [path, bytes] of tree.contents) if (path.startsWith(`${prefix}/`)) contents.set(path.slice(prefix.length + 1), bytes)
+  return {
+    inventory: {
+      root,
+      entries,
+      totalBytes: entries.reduce((sum, entry) => sum + (entry.kind === 'file' ? entry.size : 0), 0),
+      treeHash: await treeHash(entries),
+      skipped: [],
+    },
+    contents,
+  }
+}
+
+/** A nested plugin's rows, with every place and its summary named from the marketplace root. */
+function prefixed(results: readonly CheckResult[], prefix: string): CheckResult[] {
+  return results.map(result => ({
+    ...result,
+    ...(result.summary === undefined ? {} : { summary: result.summary.map((line, index) => (index === 0 ? `${prefix}: ${line}` : line)) }),
+    evidence: result.evidence.map(item =>
+      item.file === '-' || item.file === '' ? { ...item, excerpt: `${prefix}: ${item.excerpt}` } : { ...item, file: `${prefix}/${item.file}` },
+    ),
+  }))
+}
+
+/** One row per check: evidence from both, without repeats, at the worse status. */
+export function mergeResults(base: readonly CheckResult[], extra: readonly CheckResult[]): CheckResult[] {
+  const out = base.map(result => ({ ...result, evidence: [...result.evidence] }))
+  const order = { none: 0, low: 1, medium: 2, high: 3, critical: 4 }
+  for (const result of extra) {
+    const existing = out.find(item => item.id === result.id)
+    if (existing === undefined) {
+      out.push({ ...result, evidence: [...result.evidence] })
+      continue
+    }
+    const seen = new Map(existing.evidence.map((item, index) => [`${item.file}:${item.line ?? ''}:${item.excerpt}`, index]))
+    for (const item of result.evidence) {
+      const key = `${item.file}:${item.line ?? ''}:${item.excerpt}`
+      const at = seen.get(key)
+      if (at === undefined) {
+        existing.evidence.push(item)
+        continue
+      }
+      // The same place seen twice keeps the worse judgement, so a failure is
+      // never shown with only a note as its evidence.
+      const kept = existing.evidence[at] as Evidence
+      if (rankOf(item.status ?? result.status) > rankOf(kept.status ?? existing.status)) existing.evidence[at] = item
+    }
+    // A pass on one side and a note on the other stay a pass; anything worse
+    // wins, and brings its own summary, so the reason shown is the worst one.
+    if (rankOf(result.status) > rankOf(existing.status)) {
+      existing.status = result.status
+      if (result.summary !== undefined) existing.summary = result.summary
+    } else if (existing.summary === undefined && result.summary !== undefined) {
+      existing.summary = result.summary
+    }
+    if (order[result.severity] > order[existing.severity]) existing.severity = result.severity
+    existing.evidence.sort((a, b) => rankOf(b.status ?? existing.status) - rankOf(a.status ?? existing.status))
+  }
+  return out
+}
+
+function remoteSourceNote(name: string, description: string): CheckResult {
+  return {
+    id: 'structure.marketplace',
+    group: 'structure',
+    title: 'Plugins this marketplace lists',
+    status: 'info',
+    severity: 'none',
+    evidence: [{ file: '.claude-plugin/marketplace.json', excerpt: `${name} comes from ${description}: scanned when you install it`, status: 'info' }],
+    advice: 'A marketplace only lists plugins. Each one is scanned on its own when it is installed.',
+  }
+}
+
+function overflowRow(count: number): CheckResult {
+  return {
+    id: 'structure.marketplace',
+    group: 'structure',
+    title: 'Plugins this marketplace lists',
+    status: 'warn',
+    severity: 'medium',
+    evidence: [{ file: '.claude-plugin/marketplace.json', excerpt: `${count} more plugins than the ${MAX_NESTED_PLUGINS} checked here were not scanned`, status: 'warn' }],
+    advice: 'Unscanned plugins are unknown. Each one is still scanned on its own when it is installed.',
+  }
+}
+
+function missingSourceRow(name: string, path: string): CheckResult {
+  return {
+    id: 'structure.marketplace',
+    group: 'structure',
+    title: 'Plugins this marketplace lists',
+    status: 'warn',
+    severity: 'medium',
+    evidence: [{ file: '.claude-plugin/marketplace.json', excerpt: `${name} points at ${path}, which is not in this folder`, status: 'warn' }],
+    advice: 'A marketplace entry that points nowhere cannot be checked.',
+  }
+}
+
+/** In group order; inside a group, failures first, then warnings. */
+export function sortResults(results: readonly CheckResult[]): CheckResult[] {
+  const groupIndex = new Map(GROUPS.map((group, index) => [group.id, index]))
+  const statusIndex = { fail: 0, warn: 1, pass: 2, info: 3 }
+  return results
+    .map((result, index) => ({ result, index }))
+    .sort((a, b) =>
+      (groupIndex.get(a.result.group) ?? 99) - (groupIndex.get(b.result.group) ?? 99) ||
+      statusIndex[a.result.status] - statusIndex[b.result.status] ||
+      a.index - b.index,
+    )
+    .map(item => item.result)
+}
+
+function reasonOf(error: unknown): string {
+  if (error instanceof ScanError) return error.message
+  return error instanceof Error ? error.message : String(error)
+}

package/hooks/scan/verdict.ts

@@ -0,0 +1,64 @@
+import { rankOf, type CheckResult } from './checks/types'
+
+export type VerdictKind = 'safe' | 'caution' | 'reject' | 'unverified'
+
+export const RECOMMENDATION: Record<VerdictKind, string> = {
+  safe: 'Safe to install',
+  // Not a lesser "safe": powerful access worth knowing about before you install.
+  caution: 'Review what it can do',
+  reject: 'Do not install',
+  unverified: 'Could not verify',
+}
+
+export type Counts = { pass: number; warn: number; fail: number; info: number }
+
+export type Verdict = {
+  kind: VerdictKind
+  recommendation: string
+  /** Up to three: why not to install, what to watch, or why it could not be judged. */
+  reasons: string[]
+  counts: Counts
+}
+
+/**
+ * Any FAIL: do not install. Else any WARN: review what it can do. Else safe.
+ * A scan that could not finish is "could not verify" whatever it found.
+ * Rows only ever add to this: nothing a row says can lower another row.
+ */
+export function decide(results: readonly CheckResult[], error?: string): Verdict {
+  const counts: Counts = { pass: 0, warn: 0, fail: 0, info: 0 }
+  for (const result of results) counts[result.status] += 1
+  if (error !== undefined) {
+    return { kind: 'unverified', recommendation: RECOMMENDATION.unverified, reasons: [error], counts }
+  }
+  const kind: VerdictKind = counts.fail > 0 ? 'reject' : counts.warn > 0 ? 'caution' : 'safe'
+  const focus = kind === 'reject' ? 'fail' : 'warn'
+  const reasons = [...results]
+    .filter(result => result.status === focus)
+    .sort((a, b) => severityRank(b) - severityRank(a))
+    .slice(0, 3)
+    .map(reasonOf)
+  return { kind, recommendation: RECOMMENDATION[kind], reasons, counts }
+}
+
+function severityRank(result: CheckResult): number {
+  const order = { none: 0, low: 1, medium: 2, high: 3, critical: 4 }
+  return order[result.severity] * 10 + rankOf(result.status)
+}
+
+/**
+ * `Title: what it means` from the row's plain summary, or `Title: file:line
+ * what` from its worst piece of evidence when it has none.
+ */
+export function reasonOf(result: CheckResult): string {
+  const headline = result.summary?.[0]
+  if (headline !== undefined) return `${result.title}: ${headline}`
+  const worst = [...result.evidence].sort((a, b) => rankOf(b.status ?? result.status) - rankOf(a.status ?? result.status))[0]
+  if (worst === undefined) return result.title
+  return `${result.title}: ${locate(worst.file, worst.line)}${worst.excerpt}`
+}
+
+export function locate(file: string, line?: number): string {
+  if (file === '-' || file === '') return ''
+  return `${file}${line === undefined ? '' : `:${line}`} `
+}

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "ai-install-guard",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "A pre-install security gate for Claude Code: scans plugins, mods, skills and MCP servers without running them, and installs nothing until you approve.",
   "scripts": {
     "build:fixtures": "node scripts/build-fixtures.js",
+    "build:skill": "node scripts/build-skill.js",
     "sync:versions": "node scripts/sync-versions.js",
     "validate": "claude plugin validate --strict .",
-    "typecheck": "tsc -p .",
+    "typecheck": "tsc -p . && tsc -p cli",
     "test": "claude plugin test .",
-    "check": "npm run validate && npm run typecheck && npm test",
+    "test:skill": "node scripts/build-skill.js && node --test cli/scan.spec.mjs",
+    "check": "npm run validate && npm run typecheck && npm test && npm run test:skill",
     "version": "node scripts/sync-versions.js && git add .claude-plugin/"
   },
   "keywords": [
@@ -28,6 +30,7 @@
     "!hooks/**/*.test.ts",
     "!hooks/test-support/",
     "README.md",
+    "assets/",
     "CHANGELOG.md",
     "LICENSE"
   ],
@@ -43,6 +46,8 @@
     "node": ">=18"
   },
   "devDependencies": {
+    "@types/node": "^20.19.43",
+    "esbuild": "^0.28.2",
     "typescript": "^5.9.3"
   }
 }