oliver-kriska/phx-deps-vet

Deps Vet — Hex package audit ledger

Review a Hex package version, run Phase 1 supply-chain rules against it, prompt the user for a verdict, append the result to hex_vet.exs (project-root audit ledger). Vetted versions get downgraded to INFO on subsequent $phx-deps-audit runs.

Run this AFTER $phx-deps-audit to clear findings. Run this BEFORE merging a mix.lock PR to certify new versions.

Usage

$phx-deps-vet phoenix 1.7.21      # vet a single package version
$phx-deps-vet --seed              # import curated baseline seed (~30 pkgs)
$phx-deps-vet --list              # show existing ledger entries
$phx-deps-vet --check             # cross-check mix.lock vs ledger

Iron Laws

1. NEVER auto-approve. Every entry MUST come from an AskUserQuestion confirmation. Drive-by trust ruins the ledger's value.
2. Lock wins on disagreement. If mix.lock has version X and the ledger vets X-1, emit INFO and treat X as unvetted. Don't silently trust the older entry.
3. Ledger lives at project root. hex_vet.exs is a first-class security artifact, visible in PR review. Don't move it into .claude/.
4. Round-trip via inspect/2. When appending, read the file with Code.eval_file/1, mutate the map, and write back via inspect(term, pretty: true, limit: :infinity). Hand-rolled string appends drift over time.
5. Always show findings before prompting. The user must see what's being vetted. No silent :safe_to_deploy defaults.
6. Confirmation counts are COMPUTED, never estimated. Any number in an AskUserQuestion (criteria split, new/overwrite/no-op) MUST be derived from the loaded data before prompting — e.g. Enum.frequencies_by(seed.audits, & &1.criteria). Eyeballing the file and approving on wrong numbers corrupts the consent.

Execution flow

Step 1: Locate or seed hex_vet.exs

If hex_vet.exs exists at project root:
    Read it via Code.eval_file/1
Else:
    Write the empty-ledger stub (see references/hex-vet.md §"Empty ledger")
    Inform user: "Created hex_vet.exs at project root."

Step 2: Branch by mode

• <pkg> <version> → single-vet path (Step 3-7).
• --seed → import priv/hex_vet_seed.exs. Before prompting, Code.eval_file/1 the seed and compute (Iron Law #6): the criteria split (Enum.frequencies_by(seed.audits, & &1.criteria)) and, against any existing ledger, exact new / overwrite / no-op counts. Put those computed numbers in the AskUserQuestion. Also state up front that the seed is a provenance baseline, not certification of your current mix.lock (per Iron Law #2, seed versions older than the locked ones stay unvetted). Ask before overwriting existing entries.
• --list → render the audits table; exit.
• --check → compare ledger entries with mix.lock; warn on drift. Read the lock via Code.eval_file("mix.lock") with 2>/dev/null — modern locks have quoted keys and emit a found quoted keyword warning per package (tens of KB of noise that gets persisted as an oversized tool result otherwise).

Step 3: Fetch the tarball (single-vet)

Run the deps-audit corpus loader. Cache lives at ~/.cache/phx-deps-audit/corpus/<pkg>/<version>/contents/. Use:

bash ../phx-deps-audit/smoke-test/corpus.d/fetch.sh \
    <pkg> <version>

Step 4: Run Phase 1 rules

Source the rules from ../phx-deps-audit/references/rules-impl.md. Run run_all_rules over the cached dir. Write findings to a temp vet-findings.jsonl. Set FINDINGS_FILE to override default path.

Step 5: Present findings

Print the findings table per ../phx-deps-audit/references/output-renderer.md. On zero findings: say "No findings — vet from a clean baseline." On any finding: show severity, file, line, snippet inline.

Step 6: Prompt for verdict

Call AskUserQuestion with these 4 options:

• :safe_to_deploy — full trust; findings investigated and cleared.
• :safe_to_run — trust in non-production envs only (test deps).
• :does_not_implement_crypto — Mozilla-style sub-criterion.
• Skip — defer decision; don't write an entry.

If any finding is BLOCK severity: default-highlight Skip. Require explicit override before writing :safe_to_deploy over a BLOCK.

Step 7: Append to ledger

Read existing hex_vet.exs via Code.eval_file/1. Append the audit map below to :audits. Write back via Code.format_string!(inspect(...)).

%{
  package: "<pkg>",
  version: "<version>",
  criteria: <verdict_atom>,
  reviewer: "<git config user.email>",
  notes: "<user-provided one-liner OR findings summary>",
  reviewed_at: ~D[<today>]
}

Write back via Code.format_string!(inspect(term, pretty: true)). Confirm to user: "Added <pkg> <version> to hex_vet.exs."

Integration

• Run after $phx-deps-audit to clear vetted findings.
• Run before merging a mix.lock PR to certify new versions.
• Run $phx-deps-vet --check to detect ledger drift vs mix.lock.
• $phx-deps-audit auto-downgrades vetted findings to INFO.

References

• references/hex-vet.md — schema, parser, lookup
• references/seed.md — --seed flag, curated baseline
• ../phx-deps-audit/references/rules-impl.md — the same rules $phx-deps-audit runs

Out of scope (Phase 3+)

• Mix task surface — defer mix phx.deps_vet to a separate Hex package phx_deps_vet for non-CC users.
• Block-on-unvetted enforcement — defer to a PreToolUse hook that gates mix deps.get.
• Distributed imports — defer cargo-vet imports: until trust-chain semantics are designed.