ai-install-guard 0.1.0 → 0.3.0

package/hooks/scan/checks/prompts.ts

@@ -25,7 +25,8 @@ const INJECTION: readonly RegExp[] = [
 /** Text that talks to a security scanner instead of to a person. */
 const SCANNER_ADDRESS: readonly RegExp[] = [
   /\bnote\s+(?:to|for)\s+(?:the\s+|any\s+)?(?:security\s+|ai\s+|automated\s+)?(?:scanners?|reviewers?|auditors?|analy[sz]ers?)\b/i,
-  /\b(?:security\s+)?(?:scanners?|reviewers?|auditors?|analy[sz]ers?|llms?|language\s+models?|ai\s+(?:assistants?|models?|reviewers?))\b[^\n]{0,80}?\b(?:report|mark|classify|treat|consider|rate|flag|score)\b[^\n]{0,40}?\b(?:safe|pass(?:ed|ing)?|clean|benign|trusted|harmless|low[- ]risk|no\s+(?:issues|findings))\b/i,
+  // "Reviewer" or "auditor" alone is usually a person; it counts only as a tool.
+  /\b(?:(?:security|ai|automated|static|code)\s+(?:scanners?|reviewers?|auditors?|analy[sz]ers?)|scanners?|analy[sz]ers?|llms?|language\s+models?|ai\s+(?:assistants?|models?))\b[^\n]{0,80}?\b(?:report|mark|classify|treat|consider|rate|flag|score)\b[^\n]{0,40}?\b(?:safe|pass(?:ed|ing)?|clean|benign|trusted|harmless|low[- ]risk|no\s+(?:issues|findings))\b/i,
   /\b(?:this|the)\s+(?:plugin|skill|mod|code|package|repo(?:sitory)?|extension)\s+(?:is|has\s+been)\s+(?:completely\s+|totally\s+|fully\s+|100%\s+)?(?:safe|benign|harmless|verified|audited|approved)\b[^\n]{0,60}?\b(?:report|mark|pass|ignore|skip|approve)\b/i,
 ]
 
@@ -101,7 +102,9 @@ export function promptChecks(ctx: ScanContext): CheckResult[] {
       credentials.push({ file: path, line: match.line, excerpt: `names ${secretName(match)}`, status: cap(/\b(?:echo|print|printenv|cat|send|include|output)\b/i.test(lineText) ? 'fail' : 'warn') })
     }
 
-    for (const match of findAll(text, REMOTE_INSTRUCTIONS, 3)) {
+    // A local address (a preview server the skill starts) is not remote.
+    const remoteOnly = (index: number) => !/^[^\n]{0,120}?https?:\/\/(?:localhost|127(?:\.\d{1,3}){3}|\[::1\]|0\.0\.0\.0)(?![\w.-])/i.test(text.slice(index, index + 200))
+    for (const match of findAll(text, REMOTE_INSTRUCTIONS, 3, remoteOnly)) {
       remote.push({ file: path, line: match.line, excerpt: match.excerpt, status: cap('warn') })
     }
     // Telling the model to download and run code fails; a sentence warning

package/hooks/scan/checks/provenance.ts

@@ -0,0 +1,190 @@
+import { isRecord, parseJson, type ScanContext } from './context'
+import { joinPath } from './text'
+import { capEvidence, row, type CheckResult, type Evidence } from './types'
+
+const GROUP = 'provenance' as const
+const MARKETPLACE = '.claude-plugin/marketplace.json'
+const FULL_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i
+const SPECIAL_REFS = /^(?:HEAD|FETCH_HEAD|ORIG_HEAD|MERGE_HEAD|CHERRY_PICK_HEAD|REVERT_HEAD|REBASE_HEAD|BISECT_HEAD|AUTO_MERGE)$/
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/
+
+/**
+ * Group 1, for a marketplace: whether each plugin it lists from elsewhere is
+ * pinned to one commit (or one package version). A plugin that follows a
+ * branch installs whatever the branch holds that day, not what was reviewed.
+ */
+export function marketplacePinsCheck(ctx: ScanContext): CheckResult[] {
+  const parsed = parseJson(ctx.text(MARKETPLACE))
+  if (!parsed.ok || !isRecord(parsed.value) || !Array.isArray(parsed.value.plugins)) return []
+  const evidence: Evidence[] = []
+  for (const plugin of parsed.value.plugins) {
+    if (!isRecord(plugin)) continue
+    const name = typeof plugin.name === 'string' ? plugin.name : '(unnamed)'
+    const judged = judgeSource(plugin.source)
+    if (judged !== undefined) evidence.push({ file: MARKETPLACE, excerpt: `${name}: ${judged.what}`, status: judged.status })
+  }
+  if (evidence.length === 0) return []
+  return [
+    row(
+      {
+        id: 'provenance.pins',
+        group: GROUP,
+        title: 'Marketplace pins',
+        advice: 'Pin each plugin to a full commit id (sha) or an exact package version. A branch, a tag or a commit given as ref can change what installs after it was reviewed.',
+      },
+      // Every entry is judged; only the worst are listed.
+      capEvidence(evidence, 30),
+    ),
+  ]
+}
+
+function judgeSource(source: unknown): { what: string; status: 'pass' | 'warn' | 'fail' } | undefined {
+  if (typeof source === 'string') {
+    // A folder in the marketplace is pinned with the marketplace itself; one
+    // that climbs out of it is not part of what was pinned.
+    if (source.startsWith('./') || source.startsWith('../')) {
+      return joinPath('', source) === undefined ? { what: `comes from ${source}, outside the marketplace, which is not pinned with it`, status: 'warn' } : undefined
+    }
+    return { what: `comes from ${source} and follows its default branch`, status: 'warn' }
+  }
+  if (!isRecord(source)) return undefined
+  const kind = typeof source.source === 'string' ? source.source : 'unknown'
+  if (kind === 'npm' || kind === 'pip') {
+    const version = typeof source.version === 'string' ? source.version : undefined
+    const pkg = typeof source.package === 'string' ? source.package : '(package)'
+    return version !== undefined && EXACT_VERSION.test(version)
+      ? { what: `${kind} package ${pkg} at exactly ${version}`, status: 'pass' }
+      : { what: `${kind} package ${pkg} ${version === undefined ? 'at whatever version is newest' : `at ${version}, not one exact version`}`, status: 'warn' }
+  }
+  const where = typeof source.repo === 'string' ? source.repo : typeof source.url === 'string' ? source.url : kind
+  const sha = typeof source.sha === 'string' ? source.sha : undefined
+  const ref = typeof source.ref === 'string' ? source.ref : undefined
+  if (ref !== undefined && SPECIAL_REFS.test(ref)) return { what: `${where} names git's own ${ref} as its ref`, status: 'fail' }
+  if (sha !== undefined) {
+    return FULL_SHA.test(sha)
+      ? { what: `${where} pinned to commit ${sha.slice(0, 12)}`, status: 'pass' }
+      : { what: `${where} has sha "${sha.slice(0, 64)}", which is not a full commit id`, status: 'warn' }
+  }
+  if (ref !== undefined && FULL_SHA.test(ref)) {
+    return { what: `${where} gives a commit id as its ref; a branch with that name would be checked out instead, so use sha`, status: 'warn' }
+  }
+  if (ref !== undefined) return { what: `${where} follows ${ref}, which its owner can move`, status: 'warn' }
+  return { what: `${where} follows its default branch`, status: 'warn' }
+}
+
+/** What a README's AI Install Guard badge claims, read from its shields.io image. */
+export type BadgeClaim = {
+  file: string
+  line: number
+  claimed: 'safe' | 'caution' | 'reject' | 'unverified'
+  /** The version the badge names: a short commit or `tree <hash>`, when it names one. */
+  pin?: string
+  text: string
+}
+
+const BADGE_IMAGE = /img\.shields\.io\/badge\/AI(?:_|%20| )Install(?:_|%20| )Guard-([^)\s"'?]{1,300})/gi
+const HTML_BLOCK_START = /^ {0,3}<\/?[A-Za-z][\w-]*(?:\s|\/?>|$)/
+
+/**
+ * The strongest claim among the AI Install Guard badges a README shows, read
+ * the way a Markdown renderer shows it: fenced and indented code blocks and
+ * HTML comments are left out (there a badge is an example or hidden), while
+ * HTML blocks and list items, where badges usually sit indented, count. A
+ * badge whose words name no verdict is read as claiming the best one, since
+ * that is what it would make a reader think.
+ */
+export function badgeClaim(readme: { path: string; text: string } | undefined): BadgeClaim | undefined {
+  if (readme === undefined) return undefined
+  const lines = readme.text.split('\n')
+  let fence: { char: string; length: number } | undefined
+  let comment = false
+  let htmlBlock = false
+  let indentedCode = false
+  let listContext = false
+  let previousBlank = true
+  let best: BadgeClaim | undefined
+  for (let index = 0; index < lines.length; index += 1) {
+    let line = lines[index] as string
+    const blank = line.trim() === ''
+    // Inside a list item a fence may sit as deep as the item's own content.
+    const fenceIndent = listContext ? '[ \\t]{0,16}' : ' {0,3}'
+    if (fence !== undefined) {
+      // A fence closes only with its own character, at least as long, and nothing after.
+      const close = new RegExp(`^${fenceIndent}(\`{3,}|~{3,})[ \\t]*$`).exec(line)
+      if (close !== null && (close[1] as string)[0] === fence.char && (close[1] as string).length >= fence.length) fence = undefined
+      continue
+    }
+    if (comment) {
+      const end = line.indexOf('-->')
+      if (end === -1) continue
+      comment = false
+      line = line.slice(end + 3)
+    }
+    const open = htmlBlock ? null : new RegExp(`^${fenceIndent}(\`{3,}|~{3,})(.*)$`).exec(line)
+    // A backtick fence's info string cannot hold a backtick: ```x``` is inline code.
+    if (open !== null && !((open[1] as string)[0] === '`' && (open[2] as string).includes('`'))) {
+      fence = { char: (open[1] as string)[0] as string, length: (open[1] as string).length }
+      continue
+    }
+    // An HTML comment hides what it holds only when it opens a line; inline,
+    // only a closed one is a comment.
+    if (/^ {0,3}<!--/.test(line) && !line.includes('-->', line.indexOf('<!--') + 4)) {
+      comment = true
+      continue
+    }
+    const indented = /^(?: {4}|\t)/.test(line)
+    if (indentedCode && !blank && !indented) indentedCode = false
+    if (!indentedCode && indented && previousBlank && !listContext && !htmlBlock) indentedCode = true
+    if (htmlBlock && blank) htmlBlock = false
+    else if (!htmlBlock && !indentedCode && HTML_BLOCK_START.test(line)) htmlBlock = true
+    if (!blank && !indented) listContext = /^ {0,3}(?:[-*+]|\d{1,9}[.)])\s/.test(line) || (listContext && !previousBlank)
+    else if (/^ {0,3}(?:[-*+]|\d{1,9}[.)])\s/.test(line)) listContext = true
+    previousBlank = blank
+    if (indentedCode) continue
+    const shown = line.replace(/<!--[\s\S]*?-->/g, '').replace(/`[^`]*`/g, '')
+    for (const found of shown.matchAll(BADGE_IMAGE)) {
+      let message = found[1] as string
+      try {
+        message = decodeURIComponent(message)
+      } catch {
+        // Left as written.
+      }
+      const words = message.replace(/--/g, '\u0000').replace(/-[0-9a-f]{3,8}$|-[a-z]+$/i, '').replace(/_/g, ' ').replace(/\u0000/g, '-').toLowerCase()
+      const claimed = /do not install/.test(words) ? 'reject' : /could not verify/.test(words) ? 'unverified' : /caution|review what it can do/.test(words) ? 'caution' : 'safe'
+      const pin = /·\s*((?:tree\s+)?[0-9a-f]{7,64})\b/.exec(words)?.[1]
+      if (best === undefined || VERDICT_RANK[claimed] < VERDICT_RANK[best.claimed]) best = { file: readme.path, line: index + 1, claimed, pin, text: words.slice(0, 120) }
+    }
+  }
+  return best
+}
+
+const VERDICT_RANK = { safe: 0, caution: 1, unverified: 2, reject: 3 } as const
+const VERDICT_WORDS = { safe: 'Safe to install', caution: 'Review what it can do', unverified: 'Could not verify', reject: 'Do not install' } as const
+
+/**
+ * The row for a README's badge, judged against this scan's own verdict. A
+ * badge never improves a verdict: one that claims better than the scan finds
+ * is a warning, one that matches is only noted.
+ */
+export function badgeRow(claim: BadgeClaim, actual: keyof typeof VERDICT_RANK, version: { sha?: string; treeHash?: string } = {}): CheckResult {
+  const overclaims = VERDICT_RANK[claim.claimed] < VERDICT_RANK[actual]
+  // Which version the badge names, against the one scanned now.
+  const scanned = version.sha !== undefined ? version.sha.slice(0, 7) : version.treeHash !== undefined ? `tree ${version.treeHash.slice(7, 15)}` : undefined
+  const sameVersion = claim.pin !== undefined && scanned !== undefined && (claim.pin.startsWith('tree ') ? version.treeHash?.slice(7).startsWith(claim.pin.slice(5)) === true : version.sha?.startsWith(claim.pin) === true)
+  const named = claim.pin === undefined ? 'names no version' : sameVersion ? `is for this version (${claim.pin})` : `is for another version (${claim.pin})`
+  const summary = overclaims
+    ? [`The README's badge says ${VERDICT_WORDS[claim.claimed]}, but this version scans as ${VERDICT_WORDS[actual]}`, `The badge ${named}: it is outdated or was never earned`]
+    : sameVersion && claim.claimed === actual
+      ? [`The README shows an AI Install Guard badge for this version (${VERDICT_WORDS[claim.claimed]}); this scan agrees`]
+      : [`The README's badge says ${VERDICT_WORDS[claim.claimed]} and ${named}; this version scans as ${VERDICT_WORDS[actual]}`]
+  return row(
+    {
+      id: 'provenance.badge',
+      group: GROUP,
+      title: 'Review badge in the README',
+      advice: 'A badge is a picture anyone can paste. This scan is what counts: a badge that claims more than it finds is outdated or was never earned.',
+      summary,
+    },
+    [{ file: claim.file, line: claim.line, excerpt: `badge: ${claim.text}`, status: overclaims ? 'warn' : 'info' }],
+  )
+}

package/hooks/scan/checks/structure.ts

@@ -20,6 +20,7 @@ export function structureChecks(ctx: ScanContext, validator: ValidatorReport | u
     linksCheck(ctx),
     imagesCheck(ctx),
     settingsCheck(ctx),
+    filledInCheck(ctx),
   ]
 }
 
@@ -355,3 +356,94 @@ function settingsCheck(ctx: ScanContext): CheckResult {
 }
 
 export type { InventoryFile }
+
+/**
+ * Files whose real content is not in the folder: Git LFS pointers, whose file
+ * is downloaded at install, and paths a git filter rewrites on checkout. The
+ * scan reads what is stored, so the code that runs could be anything.
+ */
+function filledInCheck(ctx: ScanContext): CheckResult {
+  const evidence: Evidence[] = []
+  for (const file of ctx.files) {
+    const name = basename(file.path)
+    if (name === '.gitattributes') {
+      // A line covers the files its pattern names under its own folder:
+      // rewriting only tests or docs is noted, live code is a warning.
+      const folder = dirname(file.path)
+      const lines = (ctx.text(file.path) ?? '').split('\n')
+      for (let index = 0; index < lines.length && index < 1000; index += 1) {
+        const line = (lines[index] as string).trim()
+        if (line.startsWith('#') || line.startsWith('[attr]')) continue
+        const driver = /(?:^|\s)filter=([^\s]{1,100})/.exec(line)?.[1]
+        if (driver === undefined) continue
+        const pattern = line.split(/\s/)[0] as string
+        const coversLive = ctx.files.some(other => {
+          const rel = folder === '' ? other.path : other.path.startsWith(`${folder}/`) ? other.path.slice(folder.length + 1) : undefined
+          return rel !== undefined && attributeMatches(pattern, rel) && isLive(ctx.roleOf(other.path))
+        })
+        evidence.push({ file: file.path, line: index + 1, excerpt: `git rewrites these files with the "${driver}" filter on checkout: ${line.slice(0, 200)}`, status: coversLive ? 'warn' : 'info' })
+      }
+      continue
+    }
+    if (file.size > 1024) continue
+    const text = ctx.text(file.path)
+    if (text === undefined || !text.startsWith('version https://git-lfs.github.com/spec/')) continue
+    evidence.push({
+      file: file.path,
+      excerpt: 'a Git LFS pointer: the real file is downloaded when it is installed, and this scan could not read it',
+      // Images and docs often live in LFS; code that runs must not.
+      status: isLive(ctx.roleOf(file.path)) ? 'fail' : 'info',
+    })
+    if (evidence.length >= 20) break
+  }
+  return row(
+    {
+      id: 'structure.fetched',
+      group: GROUP,
+      title: 'Files filled in at install',
+      advice: 'The scan reads what the repository stores. A file that Git LFS downloads or a filter rewrites at install can hold different code, which was not checked.',
+    },
+    evidence,
+  )
+}
+
+/**
+ * Whether a .gitattributes pattern names `path` (relative to the attributes
+ * file's folder): no slash matches the name at any depth, a slash anchors it,
+ * `*` and `?` stay within a folder and `**` crosses them. A pattern too
+ * elaborate to match cheaply counts as matching, which can only warn more.
+ */
+export function attributeMatches(pattern: string, path: string): boolean {
+  if (pattern.endsWith('/')) return false
+  if (pattern.length > 200 || path.length > 1000 || (pattern.match(/[*?[]/g) ?? []).length > 8) return true
+  const anchored = pattern.includes('/')
+  const body = pattern.startsWith('/') ? pattern.slice(1) : pattern
+  let source = ''
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index] as string
+    if (char === '*' && body[index + 1] === '*') {
+      if (body[index + 2] === '/') {
+        source += '(?:.*/)?'
+        index += 2
+      } else {
+        source += '.*'
+        index += 1
+      }
+    } else if (char === '*') {
+      source += '[^/]*'
+    } else if (char === '?') {
+      source += '[^/]'
+    } else if (char === '[' && body.indexOf(']', index + 2) !== -1) {
+      const end = body.indexOf(']', index + 2)
+      source += `[${body.slice(index + 1, end).replace(/^!/, '^').replace(/[\\\]]/g, '\\$&')}]`
+      index = end
+    } else {
+      source += char.replace(/[.+^${}()|\\[\]]/g, '\\$&')
+    }
+  }
+  try {
+    return new RegExp(`^${source}$`).test(anchored ? path : basename(path))
+  } catch {
+    return true
+  }
+}

package/hooks/scan/checks/types.ts

@@ -50,6 +50,11 @@ export type CheckResult = {
   severity: Severity
   evidence: Evidence[]
   advice: string
+  /**
+   * What the evidence means, in plain words for a person: a headline, then a
+   * few lines. Shown before the evidence, which stays one step further in.
+   */
+  summary?: string[]
 }
 
 const RANK: Record<Status, number> = { info: 0, pass: 1, warn: 2, fail: 3 }
@@ -67,19 +72,30 @@ export function severityFor(status: Status): Severity {
   return status === 'fail' ? 'high' : status === 'warn' ? 'medium' : 'none'
 }
 
+/**
+ * At most `max` pieces of evidence, the worst first, and a line counting the
+ * rest. Every piece is judged before capping, so a late failure still counts.
+ */
+export function capEvidence(evidence: Evidence[], max: number, fallback: Status = 'warn'): Evidence[] {
+  if (evidence.length <= max) return evidence
+  const worstFirst = [...evidence].sort((a, b) => RANK[b.status ?? fallback] - RANK[a.status ?? fallback])
+  return [...worstFirst.slice(0, max), { file: '-', excerpt: `and ${evidence.length - max} more`, status: 'info' }]
+}
+
 /**
  * Builds a check's row from its evidence: the row takes the worst status any
  * piece of evidence carries (`fallback` when none does), and `pass` when
  * there is no evidence at all.
  */
 export function row(
-  base: { id: string; group: GroupId; title: string; advice: string },
+  base: { id: string; group: GroupId; title: string; advice: string; summary?: string[] },
   evidence: Evidence[],
   fallback: Status = 'warn',
   severity?: Severity,
 ): CheckResult {
   if (evidence.length === 0) {
-    return { ...base, status: 'pass', severity: 'none', evidence: [] }
+    const { summary: _unused, ...rest } = base
+    return { ...rest, status: 'pass', severity: 'none', evidence: [] }
   }
   const status = evidence.reduce<Status>((acc, item) => worse(acc, item.status ?? fallback), 'info')
   const worstFirst = [...evidence]

package/hooks/scan/checks/validator.ts

@@ -31,7 +31,7 @@ export async function runValidator(host: Host, root: string): Promise<ValidatorR
     const reason = result.stderr.trim().split('\n')[0] ?? ''
     return { ran: false, reason: reason === '' ? `exit code ${result.exitCode}` : reason.slice(0, 200) }
   }
-  const report = parseValidatorReport(parsed.value)
+  const report = relativeTo(root, parseValidatorReport(parsed.value))
   if (report.ran && parsed.value.success === false && report.errors.length === 0) {
     report.errors.push({ file: '-', message: `claude plugin validate failed (exit code ${result.exitCode})` })
   }
@@ -95,3 +95,17 @@ function splitList(text: string): string[] {
   if (current.trim() !== '') out.push(current.trim())
   return out
 }
+
+/**
+ * The report with the scanned folder's own path taken out of file names and
+ * messages: a remote scan's folder is a temporary one, and every other place
+ * in the report is relative to the candidate.
+ */
+function relativeTo(root: string, report: ValidatorReport): ValidatorReport {
+  if (!report.ran) return report
+  const roots = [root, `/private${root}`].map(path => path.replace(/\/+$/, ''))
+  const strip = (text: string): string =>
+    roots.reduce((out, path) => out.split(`${path}/`).join('').split(path).join('.'), text)
+  const fix = (item: ValidatorProblem): ValidatorProblem => ({ file: strip(item.file), message: strip(item.message) })
+  return { ...report, errors: report.errors.map(fix), warnings: report.warnings.map(fix) }
+}

package/hooks/scan/github.ts

@@ -0,0 +1,219 @@
+// What GitHub says about a repository the guard fetched from it: how old it
+// and its owner are, how many people work on it, and whether the scanned
+// commit is signed and part of the repository's own history. GitHub is the
+// host the code came from, so asking it reveals nothing new. Every answer is
+// information only, except a brand-new repository or account, and a commit
+// that is not on the default branch, which are warnings. A failed lookup is
+// noted and never fails the scan.
+
+import { row, type CheckResult, type Evidence, type Status } from './checks/types'
+import type { FetchResult, Host } from './host'
+import type { PinnedSource } from './remote'
+import { safeLine } from './safe-text'
+
+const API = 'https://api.github.com'
+const HEADERS = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'ai-install-guard' }
+const DAY = 24 * 60 * 60 * 1000
+/** Younger than this, a repository or an account is worth a warning. */
+const NEW_DAYS = 30
+
+type Json = Record<string, unknown>
+
+class LookupError extends Error {}
+
+function isJson(value: unknown): value is Json {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** owner/repo for a github.com source, or undefined for any other host. */
+export function githubRepo(url: string): { owner: string; repo: string } | undefined {
+  const match = /^https:\/\/github\.com\/([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?$/.exec(url)
+  return match === null ? undefined : { owner: match[1] as string, repo: match[2] as string }
+}
+
+async function api(host: Host, path: string): Promise<{ status: number; body: unknown; headers: Record<string, string> }> {
+  if (host.fetch === undefined) throw new LookupError('no network here')
+  let answer: FetchResult
+  try {
+    answer = await host.fetch(`${API}${path}`, { headers: HEADERS })
+  } catch (error) {
+    throw new LookupError(`could not reach GitHub: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if ((answer.status === 403 || answer.status === 429) && (answer.headers['x-ratelimit-remaining'] === '0' || answer.status === 429)) {
+    throw new LookupError("GitHub's limit for lookups without an account was reached; try again within the hour")
+  }
+  let body: unknown
+  try {
+    body = JSON.parse(answer.text)
+  } catch {
+    body = undefined
+  }
+  return { status: answer.status, body, headers: answer.headers }
+}
+
+function age(iso: unknown, now: number): number | undefined {
+  if (typeof iso !== 'string') return undefined
+  const time = Date.parse(iso)
+  return Number.isNaN(time) ? undefined : Math.max(0, Math.floor((now - time) / DAY))
+}
+
+function spoken(days: number): string {
+  if (days < 1) return 'today'
+  if (days < 60) return `${days} day${days === 1 ? '' : 's'} ago`
+  if (days < 730) return `${Math.round(days / 30)} months ago`
+  return `${Math.round(days / 365)} years ago`
+}
+
+function count(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+/** How many contributors, from the last page number of a one-per-page listing. */
+async function contributors(host: Host, path: string): Promise<number | undefined> {
+  const answer = await api(host, `${path}/contributors?per_page=1&anon=1`)
+  if (answer.status === 204) return 0
+  if (answer.status !== 200) return undefined
+  const last = /[?&]page=(\d+)>;\s*rel="last"/.exec(answer.headers.link ?? '')
+  if (last !== null) return Number(last[1])
+  return Array.isArray(answer.body) ? answer.body.length : undefined
+}
+
+export async function githubProvenance(host: Host, source: PinnedSource, now = Date.now()): Promise<CheckResult[]> {
+  const repo = githubRepo(source.url)
+  if (repo === undefined || host.fetch === undefined) return []
+  const path = `/repos/${repo.owner}/${repo.repo}`
+  try {
+    return await lookups(host, path, source, now)
+  } catch (error) {
+    const reason = error instanceof LookupError ? error.message : `the lookup failed: ${error instanceof Error ? error.message : String(error)}`
+    return [
+      {
+        id: 'provenance.repository',
+        group: 'provenance',
+        title: 'Repository and its owner',
+        status: 'info',
+        severity: 'none',
+        evidence: [{ file: '-', excerpt: `not checked: ${safeLine(reason)}`, status: 'info' }],
+        advice: "The repository's history could not be read, so the verdict rests on the code alone.",
+        summary: [`Not checked: ${safeLine(reason)}`],
+      },
+    ]
+  }
+}
+
+async function lookups(host: Host, path: string, source: PinnedSource, now: number): Promise<CheckResult[]> {
+  const repoAnswer = await api(host, path)
+  if (repoAnswer.status === 404) throw new LookupError('GitHub does not show this repository')
+  if (repoAnswer.status !== 200 || !isJson(repoAnswer.body)) throw new LookupError(`GitHub answered ${repoAnswer.status}`)
+  const info = repoAnswer.body
+  const owner = isJson(info.owner) ? info.owner : {}
+  const login = typeof owner.login === 'string' ? owner.login : undefined
+  // After the repository itself, a request that fails is noted where it
+  // belongs and the rest still count: a late failure never hides a warning.
+  const notChecked: string[] = []
+  const attempt = async <T>(what: string, run: () => Promise<T>): Promise<T | undefined> => {
+    try {
+      return await run()
+    } catch (error) {
+      notChecked.push(`${what}: ${error instanceof LookupError ? error.message : error instanceof Error ? error.message : String(error)}`)
+      return undefined
+    }
+  }
+  const ownerAnswer = login === undefined ? undefined : await attempt('its owner', () => api(host, `/users/${encodeURIComponent(login)}`))
+  const ownerInfo = ownerAnswer !== undefined && ownerAnswer.status === 200 && isJson(ownerAnswer.body) ? ownerAnswer.body : {}
+  const people = await attempt('its contributors', () => contributors(host, path))
+
+  const repoDays = age(info.created_at, now)
+  const ownerDays = age(ownerInfo.created_at, now)
+  const pushedDays = age(info.pushed_at, now)
+  const stars = count(info.stargazers_count)
+  const forks = count(info.forks_count)
+  const who = `${typeof owner.type === 'string' && owner.type === 'Organization' ? 'organization' : 'account'} ${safeLine(login ?? 'unknown')}`
+
+  // The warning signs: an account made days ago, or a new repository with a
+  // single author that hardly anyone uses. A new repository from an
+  // established account, with others working on it, is only noted.
+  const newAccount = ownerDays !== undefined && ownerDays < NEW_DAYS
+  // Only facts GitHub gave count: a count it did not give is not taken as low.
+  const loneNewRepo = repoDays !== undefined && repoDays < NEW_DAYS && people !== undefined && people <= 1 && stars !== undefined && stars < 10
+  const evidence: Evidence[] = []
+  const note = (excerpt: string, status: Status = 'info') => evidence.push({ file: '-', excerpt, status })
+  if (repoDays !== undefined) note(`created ${spoken(repoDays)}${loneNewRepo ? ', with a single contributor and few stars' : ''}`, loneNewRepo ? 'warn' : 'info')
+  if (ownerDays !== undefined) note(`owned by the ${who}, created ${spoken(ownerDays)}`, newAccount ? 'warn' : 'info')
+  note(`${stars ?? '?'} stars, ${forks ?? '?'} forks, ${people ?? '?'} contributor${people === 1 ? '' : 's'}`)
+  if (pushedDays !== undefined) note(`last pushed ${spoken(pushedDays)}`)
+  if (info.archived === true) note('archived: it gets no more fixes')
+  for (const what of notChecked) note(`not checked, ${safeLine(what)}`)
+  if (info.fork === true) {
+    const parent = isJson(info.parent) && typeof info.parent.full_name === 'string' ? safeLine(info.parent.full_name) : 'another repository'
+    note(`a fork of ${parent}: compare it with the original`)
+  }
+
+  const young = [
+    loneNewRepo && repoDays !== undefined ? `the repository is ${spoken(repoDays).replace(' ago', ' old')}, with one contributor and few stars` : '',
+    newAccount && ownerDays !== undefined ? `its owner's account is ${spoken(ownerDays).replace(' ago', ' old')}` : '',
+  ].filter(text => text !== '')
+  const summary = [
+    young.length > 0
+      ? `New: ${young.join(' and ')}`
+      : `${repoDays === undefined ? 'A repository' : `Created ${spoken(repoDays)}`} by the ${who}${ownerDays === undefined ? '' : ` (on GitHub since ${spoken(ownerDays)})`}`,
+    `${stars ?? '?'} stars, ${forks ?? '?'} forks, ${people ?? '?'} contributor${people === 1 ? '' : 's'}${pushedDays === undefined ? '' : `; last pushed ${spoken(pushedDays)}`}`,
+  ]
+  // A part that could not be read is said in the summary too, not only below it.
+  if (notChecked.length > 0) summary.push(`Not checked: ${notChecked.map(safeLine).join('; ')}`)
+  const repository = row(
+    {
+      id: 'provenance.repository',
+      group: 'provenance',
+      title: 'Repository and its owner',
+      advice: 'A brand-new repository or account has no track record. Most are honest, but most malicious plugins are new too: look closer before you trust one.',
+      summary,
+    },
+    evidence,
+    'info',
+  )
+
+  // The scanned commit: signed, and part of the repository's own history.
+  const commitEvidence: Evidence[] = []
+  const commitTried = await attempt('the commit', () => api(host, `${path}/commits/${source.sha}`))
+  const commit = commitTried ?? { status: 0, body: undefined, headers: {} }
+  if (commitTried === undefined) {
+    commitEvidence.push({ file: '-', excerpt: `not checked: ${safeLine(notChecked.at(-1) ?? 'the request failed')}`, status: 'info' })
+  } else if (commit.status === 200 && isJson(commit.body) && isJson(commit.body.commit)) {
+    const verification = isJson(commit.body.commit.verification) ? commit.body.commit.verification : {}
+    const committer = isJson(commit.body.commit.committer) ? commit.body.commit.committer : {}
+    const committedDays = age(committer.date, now)
+    commitEvidence.push({
+      file: '-',
+      excerpt: verification.verified === true ? 'signed, and GitHub verified the signature' : 'not signed, or the signature could not be verified',
+      status: 'info',
+    })
+    if (committedDays !== undefined) commitEvidence.push({ file: '-', excerpt: `committed ${spoken(committedDays)}`, status: 'info' })
+  } else if (commit.status === 404 || commit.status === 422) {
+    commitEvidence.push({ file: '-', excerpt: 'GitHub does not show this commit in this repository', status: 'warn' })
+  } else if (commitTried !== undefined) {
+    commitEvidence.push({ file: '-', excerpt: `not checked: GitHub answered ${commit.status}`, status: 'info' })
+  }
+  // A commit named by id could come from a fork in the same network (an
+  // "impostor commit"); one reached through a branch or tag cannot.
+  const defaultBranch = typeof info.default_branch === 'string' ? info.default_branch : undefined
+  if (source.refKind === 'commit' && defaultBranch !== undefined && commit.status === 200) {
+    const compared = (await attempt('the default branch', () => api(host, `${path}/compare/${encodeURIComponent(defaultBranch)}...${source.sha}`))) ?? { status: 0, body: undefined, headers: {} }
+    const status = isJson(compared.body) && typeof compared.body.status === 'string' ? compared.body.status : undefined
+    if (status === 'behind' || status === 'identical') commitEvidence.push({ file: '-', excerpt: `part of the default branch ${safeLine(defaultBranch)}`, status: 'info' })
+    else if (status !== undefined) commitEvidence.push({ file: '-', excerpt: `not on the default branch ${safeLine(defaultBranch)}: it may come from another branch or from a fork`, status: 'warn' })
+    else commitEvidence.push({ file: '-', excerpt: `whether it is on the default branch was not checked: ${compared.status === 0 ? safeLine(notChecked.at(-1) ?? 'the request failed') : `GitHub answered ${compared.status}`}`, status: 'info' })
+  }
+  const commitRow = row(
+    {
+      id: 'provenance.commit',
+      group: 'provenance',
+      title: 'The scanned commit',
+      advice: "A commit named by its id can come from any fork of the repository, since GitHub serves them all from one place. Prefer one on the default branch or behind a release tag.",
+      summary: commitEvidence.length > 0 ? [commitEvidence.map(item => item.excerpt).join('; ').replace(/^./, char => char.toUpperCase())] : undefined,
+    },
+    commitEvidence,
+    'info',
+  )
+  return [repository, commitRow]
+}

package/hooks/scan/host.ts

@@ -32,7 +32,20 @@ export type RunOptions = {
   env?: Record<string, string>
 }
 
+/** An HTTP answer, the body read as text. */
+export type FetchResult = {
+  status: number
+  ok: boolean
+  /** Lower-cased names. */
+  headers: Record<string, string>
+  text: string
+}
+
+export type FetchInit = { method?: string; headers?: Record<string, string>; body?: string }
+
 export type Host = {
+  /** HTTPS requests, for repository metadata and the lookups you turn on. Absent where there is no network. */
+  fetch?: (url: string, init?: FetchInit) => Promise<FetchResult>
   list: (path: string) => Promise<HostEntry[]>
   stat: (path: string, options?: { resolve: boolean }) => Promise<HostStat>
   readBytes: (path: string) => Promise<Uint8Array>