{"_id":"@elgabor/npm-package-guard","name":"@elgabor/npm-package-guard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@elgabor/npm-package-guard","version":"0.1.0","description":"Install and update a Codex skill that audits npm supply-chain risk before packages run.","license":"MIT","author":{"name":"Lorenzo Borgato"},"type":"commonjs","bin":{"npm-package-guard":"bin/cli.js"},"scripts":{"test":"node skill/scripts/test.js && node tests/cli.test.js","prepack":"npm test"},"engines":{"node":">=18"},"repository":{"type":"git","url":"git+https://github.com/Elgabor/personal-skills.git","directory":"npm-package-guard"},"homepage":"https://github.com/Elgabor/personal-skills/tree/main/npm-package-guard#readme","bugs":{"url":"https://github.com/Elgabor/personal-skills/issues"},"keywords":["codex","npm","security","supply-chain","skill"],"publishConfig":{"access":"public"},"gitHead":"75a389c58f0672a4699e9941d90187afcda98a69","_id":"@elgabor/npm-package-guard@0.1.0","_nodeVersion":"22.22.3","_npmVersion":"11.18.0","dist":{"integrity":"sha512-N4YG3yAhVj9S9Pq98MfU1VkNbf9wKrAAc4QMw0tw2rZe5DiHTx41JsJ9CsT/tn/KTiIKNXQ33ykNZxpTAk37yA==","shasum":"ea77f605dc030ffbf3d5602a0ae34296cb1f36f5","tarball":"https://registry.npmjs.org/@elgabor/npm-package-guard/-/npm-package-guard-0.1.0.tgz","fileCount":11,"unpackedSize":71881,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCpgA8cqTQo1mBUECJ9rqBW1sh9/gxW85DU45g+WKegkgIgNYsq/O+4NzaC0/mjNxcAYI7Ks+KekGicmEnOiDN8uIU="}]},"_npmUser":{"name":"elgabor","email":"l.borgato12@gmail.com"},"directories":{},"maintainers":[{"name":"elgabor","email":"l.borgato12@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/npm-package-guard_0.1.0_1784608425006_0.3782411048242209"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T04:33:44.769Z","0.1.0":"2026-07-21T04:33:45.160Z","modified":"2026-07-21T04:33:45.331Z"},"maintainers":[{"name":"elgabor","email":"l.borgato12@gmail.com"}],"description":"Install and update a Codex skill that audits npm supply-chain risk before packages run.","homepage":"https://github.com/Elgabor/personal-skills/tree/main/npm-package-guard#readme","keywords":["codex","npm","security","supply-chain","skill"],"repository":{"type":"git","url":"git+https://github.com/Elgabor/personal-skills.git","directory":"npm-package-guard"},"author":{"name":"Lorenzo Borgato"},"bugs":{"url":"https://github.com/Elgabor/personal-skills/issues"},"license":"MIT","readme":"# NPM Package Guard\n\nA Codex skill that checks direct npm dependencies before untrusted package code\ncan run. It can audit the repository you are working in on demand or add an\noptional Codex hook that intercepts package installation commands.\n\nNPM Package Guard is a focused pre-install gate, not a promise that a package is\nsafe. It combines registry metadata with OSV vulnerability data and produces a\nsmall `PASS`, `WARN`, or `BLOCK` report that an agent and a human can review.\n\n## Quick start\n\nInstall or run the setup wizard without a global npm installation:\n\n```bash\nnpx --yes @elgabor/npm-package-guard@latest\n```\n\nThe skill is copied to:\n\n```text\n$CODEX_HOME/skills/npm-package-guard\n```\n\nWhen `CODEX_HOME` is not set, it uses `~/.codex/skills/npm-package-guard`.\nRestart Codex or open a fresh task after installation so skill discovery is\nrefreshed.\n\nThen open any npm repository and invoke:\n\n```text\n$npm-package-guard\n```\n\nNo additional prompt is required. The current repository is audited and no\npackage is installed.\n\n## What it checks\n\nFor each direct dependency, NPM Package Guard prefers the exact version from an\nnpm, pnpm, Yarn, or Bun lockfile and checks:\n\n- known vulnerabilities reported by OSV\n- names suspiciously similar to popular packages\n- `preinstall`, `install`, and `postinstall` lifecycle scripts\n- versions published less than 72 hours ago\n- maintainer or publisher changes\n- registry deprecation notices\n- newly introduced command-line binaries\n- regressions in registry provenance or trusted-publisher signals\n- npm aliases, resolved to their real registry package\n\nRepository audits use bounded concurrency to keep larger dependency sets fast.\n\n## Results\n\n| Result | Meaning |\n| --- | --- |\n| `PASS` | None of the implemented checks fired. This is not proof of safety. |\n| `WARN` | A named signal requires review before installation. |\n| `BLOCK` | Reject that version and audit a replacement. |\n| Operational warning | A service or check was unavailable. Retry instead of treating it as approval. |\n\nExample:\n\n```text\n| package | version | verdict | reason |\n|---|---|---|---|\n| react | 19.2.0 | PASS | no checked risk signals |\n| example-cli | 1.0.0 | WARN | release is less than 72 hours old |\n| vulnerable-package | 1.2.3 | BLOCK | OSV advisory GHSA-... |\n```\n\n## Optional automatic hook\n\nSetup asks whether you want automatic protection. The default is **No**. Merely\ninstalling or invoking the skill never changes Codex hooks.\n\nEnable it later with:\n\n```bash\nnpx --yes @elgabor/npm-package-guard@latest enable-hook\n```\n\nThe hook runs before Codex Bash commands. Unrelated commands take a fast path\nwith no subprocess or network request. Commands such as `npm install`,\n`pnpm add`, `yarn add`, `bun add`, and explicit `npx --package` installs are\nparsed and checked before execution.\n\nIn hook mode:\n\n- one `BLOCK` stops the install\n- two independent `WARN` signals stop the install\n- unavailable registry, OSV, or checker services warn and fail open so the\n  shell cannot be permanently bricked\n\nAfter enabling the hook, run `/hooks` in Codex and trust the new entry. Until\nthat step succeeds, do not assume enforcement is active.\n\nThe automatic hook currently supports macOS and Linux and requires `/bin/bash`\nand an existing `jq` installation. The manual audit only requires Node.js.\n\nDisable the hook with:\n\n```bash\nnpx --yes @elgabor/npm-package-guard@latest disable-hook\n```\n\nExisting Codex hook entries are preserved. Configuration changes are backed up,\nand only the NPM Package Guard entry is removed.\n\n## Commands\n\n```bash\n# Install and optionally choose the hook interactively\nnpx --yes @elgabor/npm-package-guard@latest\n\n# Install without prompting for the hook\nnpx --yes @elgabor/npm-package-guard@latest install --no-hook\n\n# Install and explicitly enable the hook\nnpx --yes @elgabor/npm-package-guard@latest install --hook\n\n# Update managed files while preserving the allowlist\nnpx --yes @elgabor/npm-package-guard@latest update\n\n# Show installed and hook status\nnpx --yes @elgabor/npm-package-guard@latest status\n\n# Enable or disable automatic interception\nnpx --yes @elgabor/npm-package-guard@latest enable-hook\nnpx --yes @elgabor/npm-package-guard@latest disable-hook\n\n# Recoverable uninstall\nnpx --yes @elgabor/npm-package-guard@latest uninstall\n```\n\nUpdates replace managed skill files atomically, preserve `allowlist.txt`, and\nkeep a timestamped backup of the previous version. Uninstall first removes the\nhook and then moves the skill to a timestamped recovery directory instead of\ndeleting it permanently.\n\n## Allowlist\n\nThe installed `allowlist.txt` accepts one entry per line:\n\n```text\npackage-name\npackage-name@1.2.3\n@scope/package\n@scope/package@2.0.0\n```\n\nUse an allowlist only after reviewing and accepting the specific risk. Updates\npreserve the user's installed allowlist.\n\n## Privacy and network access\n\nNPM Package Guard has no telemetry, account, analytics, or external package\ndependencies. During an audit it sends package names and versions only to:\n\n- the public npm registry for package metadata\n- the public OSV API for vulnerability lookup\n\nIt does not upload repository source code.\n\n## Scope and limitations\n\nThe current release intentionally focuses on a small, explainable pre-install\ngate. It does not perform:\n\n- static analysis of downloaded tarballs\n- complete transitive dependency interception\n- cryptographic provenance verification\n- post-install lockfile diffing\n- malware sandboxing\n\nUse it alongside lockfiles, code review, npm audit, CI, and normal dependency\nhygiene.\n\n## Development\n\n```bash\ngit clone https://github.com/Elgabor/personal-skills.git\ncd personal-skills/npm-package-guard\nnpm test\nnpm pack --dry-run\n```\n\nTests cover command parsing, manager variants, aliases, lockfiles, OSV results,\ntimeouts, hook configuration preservation, installer updates, allowlist\npreservation, and recoverable uninstall.\n\n## License\n\nMIT © Lorenzo Borgato\n","readmeFilename":"README.md","_rev":"1-5562f8c82000774d9d8e8dfa8f62c7d7"}