trust-npm

trust-npm is a production-oriented npm wrapper that blocks unknown dependencies by default and requires explicit approvals.

It uses your existing package-lock.json as a trust baseline and intercepts npm install before allowing package installation.

Features

• Default-deny installs for unknown packages
• Trust baseline bootstrapped from package-lock.json
• Risk scoring for unknown packages (age, downloads, repo, naming pattern)
• Human-gated approvals (request-approve + human approve)
• Cross-platform npm passthrough using child_process.spawn

Install

npm install
npm run build
npm link

Then use:

trust-npm --help

One-command project setup

If you want npm commands to go through trust-npm automatically:

trust-npm init

This will:

• create/update .trust-npm.json from package-lock.json
• persist alias npm -> trust-npm in your shell profile
• install npm takeover shim so plain npm routes through trust-npm
• print current-session refresh commands and resolution check
• add/update AGENTS.md with trust-npm usage policy

You can force shell target:

trust-npm init --shell powershell
trust-npm init --shell bash
trust-npm init --shell zsh

Commands

trust-npm init

Initializes .trust-npm.json, sets shell alias, enables npm takeover, prints shell refresh guidance, and writes agent guidance.

trust-npm init

Skip automatic alias setup:

trust-npm init --skip-alias

Enable npm takeover shim:

trust-npm init --takeover

Show immediate shell refresh instructions/check:

trust-npm init --takeover --refresh-shell

Disable takeover if needed:

trust-npm init --no-takeover

Disable session refresh guidance/check output:

trust-npm init --no-refresh-shell

Optional alias instructions:

trust-npm init --print-shell-alias

trust-npm install <package...>

Intercepts install requests and blocks unknown packages until explicitly approved.

trust-npm install lodash
trust-npm install react -D

If blocked:

❌ BLOCKED (high risk): fast-ultra-db-kit
Reason:
- Published 2 day(s) ago
- 12 weekly downloads
- Missing repository field
- Risk score: 90/50

Run:
trust-npm request-approve fast-ultra-db-kit --reason "needed for feature X"
Then a human runs:
trust-npm approve fast-ultra-db-kit

trust-npm approve <package...>

Human-only command. Adds packages to trusted store after explicit confirmation:

trust-npm approve lodash
trust-npm approve react react-dom

trust-npm request-approve <package...>

Agent-safe command to request approval for human review:

trust-npm request-approve react-pivot-pro --reason "needed for dashboard POC"

trust-npm status

Shows high-level trust status for the current project:

trust-npm status

Trust Store Format

.trust-npm.json:

{
  "version": 1,
  "createdAt": "2026-04-04T10:00:00.000Z",
  "updatedAt": "2026-04-04T10:05:00.000Z",
  "trustedPackages": {
    "lodash": {
      "source": "lockfile",
      "approvedAt": "2026-04-04T10:00:00.000Z"
    },
    "fast-ultra-db-kit": {
      "source": "manual",
      "approvedAt": "2026-04-04T10:05:00.000Z"
    }
  },
  "riskThreshold": 50
}

Security Model

• Unknown package install attempts are blocked.
• High-risk unknown packages are called out with detailed risk factors.
• Even low-risk unknown packages are still blocked until approved.
• No silent approvals.

Notes

• trust-npm install forwards to real npm install only when checks pass.
• If you run plain npm install, trust checks are bypassed. Use shell aliasing if desired.
• Network access to npm registry is required for risk analysis on unknown packages.

Future Extensions

The structure is prepared for:

• additional package manager adapters (for example, pip)
• runtime import/require protection
• CI/CD enforcement mode