depcurfew

One supply-chain security policy for npm, pnpm, Yarn, Bun, Deno, uv, pip, Poetry, PDM, Pipenv, Renovate and Dependabot, and a doctor that finds configuration that silently does nothing.

Why

Package managers and update bots now each protect you against freshly published malicious versions: a release-age delay, an allow-list for install scripts, limits on git and tarball dependencies. Each tool names these settings differently, counts time in its own unit, reads them from its own files and supports them only from some version on. A setting can also look right and do nothing, for example because CI pins an older version of the package manager, or because a bot proposes versions the package manager would refuse.

depcurfew keeps one policy file, depcurfew.json, writes it into the configuration of every tool in the repository, and checks that the result really works.

Five-minute start

1. npx depcurfew init writes depcurfew.json with the default policy below and lists the tools it detected. When the repository already sets a longer release-age delay for one of them, cooldown.minimum keeps the longest one, and init says where it found it.
2. npx depcurfew explain shows what it detected and what the policy means for each tool.
3. npx depcurfew apply --dry-run prints the changes as a diff, without writing anything.
4. npx depcurfew apply writes them. Run it again whenever depcurfew.json changes; a second run with the same policy changes nothing.
5. npx depcurfew doctor reports configuration that silently does not work and drift from the policy, and exits with 1 when it finds an error.
6. Add the GitHub Action so that doctor runs on every push and reports to code scanning.

The default policy:

{
  "$schema": "https://unpkg.com/depcurfew/schema.json",
  "version": 1,
  "cooldown": {
    "minimum": "3d",
    "exclude": [],
    "securityUpdates": "bypass"
  },
  "installScripts": {
    "default": "deny",
    "allow": [],
    "deny": []
  },
  "sources": {
    "git": "deny",
    "remoteTarball": "deny",
    "file": "allow",
    "directory": "allow"
  },
  "targets": "auto"
}

Installation

depcurfew needs Node.js 22 or later and has a single runtime dependency, yaml.

Add it to the project as a development dependency, so the team, CI and coding agents all run the version pinned in the lockfile. Once apply has written the project's release-age delay, later updates of depcurfew go through that delay as well:

npm install --save-dev depcurfew
npx dcf doctor

Who needs it installed:

• Developers working on the project: nothing to do. The protection does not depend on depcurfew being installed: it lives in the package manager configuration that apply writes into the repository (.npmrc, package.json, pnpm-workspace.yaml, .yarnrc.yml, bunfig.toml, deno.json, pyproject.toml or uv.toml, poetry.toml, Pipfile, requirements.txt and the bot configuration), and the package managers read it on their own. pip's release-age delay is the exception: pip reads it only from the environment where it runs, and apply says what to set there. The project install brings depcurfew along as a development dependency anyway.
• Whoever changes depcurfew.json: runs npx dcf apply and commits the result.
• CI: runs doctor, with the GitHub Action below or with the project's own copy on other CI systems.

A global install (npm install -g depcurfew) works, but teams should not rely on it: each machine may run a different version, the lockfile does not pin it, and npm does not read the project's .npmrc in global mode, so the project's release-age delay does not cover the install.

To work on depcurfew itself, run it from a clone of this repository:

git clone https://github.com/DevXord/depcurfew.git
cd depcurfew
npm ci
npm run build
node dist/cli.js doctor /path/to/your/repository

The policy file

Every section is optional: a section that is absent means depcurfew does not manage that area. Durations are converted to each tool's own unit and always rounded up, so a tool never waits less than the policy says. Where a tool cannot express part of the policy, depcurfew says so instead of skipping it silently.

Commands

The package installs two names for the same command: depcurfew and the short dcf, so dcf doctor works like depcurfew doctor.

Without a directory, explain, apply and doctor work on the nearest directory with depcurfew.json, from the current directory up to the root of the repository (the directory with .git), and say so when that is a parent directory (outside a git repository only the current directory counts, and on Linux and macOS a parent directory counts only when it belongs to you and others cannot write to it, because a shared parent such as /tmp may hold someone else's depcurfew.json; directories inside node_modules are skipped), so doctor run in a subdirectory does not pass for a project without a policy. A directory given on the command line is used as it is. check looks for depcurfew.json the same way, starting in --dir.

Exit codes: 0 success (warnings included), 1 an error (an invalid or unreadable policy, a file that cannot be edited, a doctor finding with level error), 2 a usage error (such as an unknown option or a directory that does not exist). depcurfew <command> --help describes a command with examples and its exit codes.

Every finding and warning says what to do about it. When a command cannot start, it says why with a code (directory-not-found, not-a-directory, policy-missing, policy-invalid, policy-unreadable, and for init also policy-exists and cannot-write) and what to do; with --json that is a document with errors on stdout, and doctor --sarif prints a run marked as not successful. Text for people is colored on a terminal; NO_COLOR=1 turns colors off and FORCE_COLOR=1 turns them on, for example in a CI log that shows them. Control characters in names and values from the repository or a registry are shown as text (ESC as \x1b, or as \u001b inside a quoted value such as a package name in the problems of depcurfew.json), so a crafted package or file name cannot change the terminal. --json, --sarif and a diff written to a file stay plain, for programs and AI agents.

The --json documents of all commands share these fields: schemaVersion (1), policy (its status in apply and doctor, the path of the depcurfew.json used in check, its values in explain), notices (such as the parent directory whose depcurfew.json was used) and errors, the reasons a command could not start, each with code, level, location.file, message and fix, and issues for policy-invalid. Paths are relative to the directory the command works on (a directory that does not exist is named as given). A depcurfew.json that cannot be used is an error with the same code, message and fix in apply, check and explain, which also keeps it in policy; doctor reports it as the finding invalid-policy, so that it reaches code scanning too, and counts it in summary.error. Within a schemaVersion fields and values are only added; a field is removed or changes its meaning only with a new schemaVersion.

How apply edits files:

• It keeps comments, formatting, line endings and key order. In line-based files (INI, TOML) it writes a block between # >>> depcurfew managed block and # <<< depcurfew managed block markers and comments out older copies of the settings it manages (they come back when the policy stops managing them); in YAML it marks the keys it writes with # managed by depcurfew; JSON files keep their comments and indentation.
• It reads files the way the tool does. In YAML files of a tool whose loader applies merge keys (<<: *defaults in pnpm-workspace.yaml and pnpm's config.yaml), a setting a merge key brings in counts, and apply writes its value into the map itself, which wins over merged keys; .yarnrc.yml and dependabot.yml are read without merging. A switch that allows every install script counts as on for every value the tool does not read as off: pnpm runs every build script for dangerouslyAllowAllBuilds: "false" (a string) or yes, and npm and pnpm 10 for =1 or =yes in .npmrc.
• It never removes settings it does not manage. Allow-lists are only added to; exception lists follow the policy, except the entries Renovate adds to pnpm's exception list for security updates, which stay with their comment. An entry in a tool's own install-script list that contradicts installScripts (it lets a package of installScripts.deny run its scripts, or blocks one of installScripts.allow) stays as it is, with the warning deny-conflicts-with-file, and apply records no denial for that package.
• When it replaces a longer release-age delay someone set by hand with the policy's shorter one, it warns (cooldown-shortened) and names the cooldown.minimum that keeps it.
• If any file cannot be edited, nothing is written. If a file cannot be written, the files already written are put back.
• It does not create bot configuration files or project manifests (package.json, deno.json, pyproject.toml, Pipfile, requirements.txt); it creates a package manager's configuration file when it is missing. A package manager seen only in a CI setup step, with nothing of it in the repository, is not configured under targets: "auto".
• It warns when a file it writes is ignored by git (.gitignore or .git/info/exclude), because the change would then stay on one machine.

apply warnings and errors

Each warning and error of apply has a code. The text output shows it in parentheses after the message, with what to do on the next line, like a doctor finding. depcurfew apply --json (also with --dry-run) prints one JSON document and nothing on stderr: changes (each file with its action and unified diff), warnings and errors (each with code, level, message and fix; tool when it concerns one tool; location when it concerns one file, with file and, when known, line; for an invalid policy also issues), snippets to add by hand, notices (such as the parent directory whose depcurfew.json was used) and written. A run that writes nothing because of an error lists no changes and exits with 1. Diffs, on the terminal, in a pipe and in changes, show the values of secrets as <redacted> (_authToken, _auth and _password in .npmrc, keys ending in token or password, the user and password of a URL), so that a diff can be shared or logged; the files keep them. The text diff also shows control and bidirectional characters from the files as text (\x1b, ‮), so that a value cannot drive the terminal or a CI log; changes keeps them, escaped by JSON.

Warnings:

• warning nothing-to-configure: depcurfew found no supported package manager or bot, so nothing is configured.
• warning environment-overrides: apply --user: an environment variable makes a tool read another user file or none, or overrides a value apply writes there.
• warning depcurfew-outdated: The project installs a newer depcurfew than the one running, which may not know settings that version writes.
• warning file-unreadable: A file that shows which tools a project uses cannot be read or parsed (too large, a symlink out of the repository, no read permission, invalid), so depcurfew may configure fewer tools than the project uses.
• warning tool-not-supported: A detected or installed tool is not supported (Yarn Classic), so nothing is written for it.
• warning tool-only-in-ci: A tool appears only in a CI setup step, with no manifest, lockfile or configuration in the repository, so targets "auto" does not configure it.
• warning version-not-pinned: No exact version of a package manager is pinned, so depcurfew configures for the latest version it knows.
• warning version-too-old: The pinned version of a tool (with apply --user, the installed one) lacks a setting the policy needs, so that setting is not written.
• warning version-unknown: apply --user: the installed version of a tool cannot be read from its files, and a value it does not understand would stop every command, so nothing is written for it.
• warning no-user-config: apply --user: the tool has no user-level configuration file, so nothing is written for it.
• warning user-setting-project-only: apply --user: the tool reads a part of the policy only from project files, so it is not written into the user file.
• warning user-directory-relative: apply --user: the environment variable that names the directory of the user file (XDG_CONFIG_HOME, APPDATA) is a relative path, so the tool looks in another place from each directory, or where it looks then is not known; nothing is written for it.
• warning user-setting-overridden: apply --user: a file the tool reads ahead of its user file (~/.npmrc for pnpm 10) sets a key apply writes there to another value, so the value written has no effect.
• warning version-not-used: apply --user: --for gives the version of a tool that apply --user does not configure (not in PATH with targets "auto", or not listed under targets).
• warning cooldown-not-written: The release-age delay cannot be written for a tool.
• warning cooldown-shortened: A release-age delay set outside depcurfew's markers (in JSON files also one an earlier apply wrote) is longer than the policy, and apply replaces it with the shorter one.
• warning cooldown-environment-only: pip reads no project configuration, so the release-age delay has to be set in the environment where pip runs.
• warning exclude-pattern-unsupported: A cooldown exception uses a wildcard the tool does not support, so it is not written.
• warning exclude-unsupported: The tool has no setting for cooldown exceptions, so the release-age delay applies to every package.
• warning allow-pattern-unsupported: An installScripts.allow entry is a pattern, but the tool takes package names only, so it is not written.
• warning deny-pattern-unsupported: An installScripts.deny entry is a pattern, but the tool records denials by package name only, so it is not written.
• warning allow-all-unsupported: The tool has no setting that allows every install script, so installScripts "allow" is not written.
• warning allow-all-replaced: A setting that allowed every install script (with any value the tool reads as true, also one that a YAML merge key brings in, or pnpm 10's dangerously-allow-all-builds in .npmrc) was set to false, because the policy denies install scripts.
• warning allow-list-entry-outside-policy: An install-script allow-list in the repository (with apply --user, in a user file) lets a package run scripts the policy does not allow; apply does not remove it.
• warning deny-conflicts-with-file: An entry in a tool's own list lets a package of installScripts.deny run its install scripts, or blocks a package of installScripts.allow; apply does not change entries it did not write.
• warning unexpected-value: A setting apply adds to has a value of a type the tool does not accept there, so apply leaves it as it is and writes nothing into it.
• warning built-in-list-replaced: Bun's built-in list of trusted packages is replaced by the policy's allow-list.
• warning scripts-not-enforceable: The pinned (with apply --user, the installed) npm or pnpm runs every install script and has no allow-list, so "deny" cannot be enforced.
• warning before-overrides-cooldown: before= in .npmrc takes the place of the release-age delay apply writes, or makes npm stop with an error next to it (apply --user then does not write the delay).
• warning exact-version-gap: The pinned (with apply --user, the installed) pnpm skips the release-age delay for packages requested by exact version.
• warning source-not-enforceable: The tool has no setting for a dependency source the policy denies; doctor checks the lockfile instead.
• warning source-switch-indirect-only: The pnpm setting for git and tarball sources stops them only for indirect dependencies.
• warning source-switch-combined: One pnpm setting covers git and tarball sources, so denying one denies both.
• warning forced-source-build: Python packages on the allow-list are always built from source, because no tool can only allow a build.
• warning build-switch-scope: The tool's switch forbids building only packages from an index; git, local and archive dependencies are still built.
• warning build-switch-install-only: Poetry applies its build switch when installing; poetry lock may still build source distributions.
• warning build-switch-environment-only: The tool has no project setting that forbids building from source, so it has to be set in the environment where the tool runs.
• warning requirements-file-missing: There is no requirements file to write pip options into.
• warning manifest-missing: A setting belongs in a project manifest (package.json, deno.json, pyproject.toml, Pipfile) that does not exist, and apply does not create manifests.
• warning lockfile-out-of-date: The lockfile records, or is checked against, a setting apply changed, so it has to be locked again.
• warning file-ignored-by-git: A file apply writes matches a .gitignore rule, so the change may never reach the repository.
• warning bot-config-missing: A bot has no configuration file, and depcurfew does not create one.
• warning bot-config-not-edited: A bot configuration file is in a place or format depcurfew does not edit; a snippet shows what to add.
• warning bot-entries-missing: The Dependabot configuration has no entries for the package managers in use.
• warning security-delay-unsupported: Dependabot cannot delay security updates, so securityUpdates "delay" is not applied.

Errors (nothing is written):

• error cannot-edit: A file cannot be read or edited safely (invalid syntax, a symlink, a style depcurfew does not edit), so nothing is written.
• error cannot-write: A file cannot be written (no permission, a read-only file system, a full disk, a directory or symlink in its place); the files already written are put back, so nothing changes.
• error policy-missing: The directory has no depcurfew.json.
• error policy-invalid: depcurfew.json does not follow the schema; issues lists the problems.
• error policy-unreadable: depcurfew.json cannot be read.
• error policy-exists: depcurfew init found a depcurfew.json and writes it only with --force.
• error directory-not-found: The directory given on the command line does not exist or cannot be opened.
• error not-a-directory: The path given on the command line is a file, not a directory.
• error home-missing: apply --user and init --user: the home directory (HOME, USERPROFILE on Windows) does not exist or is not an absolute path, so nothing is written.

Protecting the whole machine

depcurfew apply protects one project. The user-level configuration of each package manager protects every project on the machine that does not set the same settings itself, and also what runs outside a project: npx, uvx, global installs, and a new project before anyone ran apply in it.

depcurfew init --user
depcurfew apply --user --dry-run
depcurfew apply --user
depcurfew doctor --user

• The user policy is ~/.config/depcurfew/depcurfew.json (in $XDG_CONFIG_HOME/depcurfew/ when that variable is set to an absolute path, in %APPDATA%\depcurfew\ on Windows). It has the same format as a project policy; under targets: "auto" it configures the package managers found in PATH.
• depcurfew does not run other programs to learn their versions. It reads the version from the files next to the executable in PATH: the package.json of a tool installed from npm, the .dist-info folder of one installed from PyPI. When it cannot, it configures for the latest version it knows and says so, except for tools that stop every command on a value their version does not understand (the last column below): for those it writes nothing until you pass the version, for example --for uv@0.13.6.
• apply --user writes the files of all tools or none, as apply does in a project: a user file it cannot read or edit (not UTF-8, a symlink, larger than 1 MiB, a file where its directory belongs) is an error that names it, such as ~/.config/pip/pip.conf, with a fix for that problem, and a file that cannot be written puts back the ones already replaced. init --user and apply --user do not create a missing home directory, and when XDG_CONFIG_HOME or %APPDATA% is a relative path, apply --user writes nothing for the tools that may use it, with a warning (pip then reads pip.conf relative to the directory each command runs in). Run as root (sudo with HOME kept), they leave each file they replace to its owner, and give what they create in the home directory to the owner of the home directory.
• A key apply --user writes into a user file can be overridden by a file the tool reads ahead of it: pnpm 10 reads ~/.npmrc before its rc file. apply --user warns about a different value there (user-setting-overridden) with the line, and doctor --user reports it.
• A tool's own project settings win over its user file for the same key. Parts of the policy that a tool reads only from project files, such as per-package allow-lists, are not written into the user file; apply --user names them, and depcurfew apply in the project writes them.
• A user file is edited as apply edits a project file: a setting the policy manages that is set by hand elsewhere in the file is commented out and comes back when the policy stops managing it (YAML files get the policy's value instead). That includes an exception list the policy leaves empty, the command sections of pip.conf such as [install], and the [pip] table of uv.toml. Install-script allow-list entries that the policy does not allow are kept and reported; a longer delay that the policy shortens is reported.
• doctor --user reports a user file that does not match the user policy, values in user files that weaken every project, and environment variables that make a tool read another file, no file or other values, such as a relative XDG_CONFIG_HOME. It reads values as each tool does: a switch that allows every install script is on for every value the tool does not read as off (dangerously-allow-all-builds=1 in ~/.npmrc for pnpm 10), and a merge key (<<: *defaults) counts in pnpm's config.yaml. A missing home directory, or a user file it cannot read, is an error rather than a clean report.
• Tools that record the release-age delay in their lockfile may lock differently on a machine whose user file sets one than on a machine without it; set the same delay in the project with depcurfew apply so that every machine and CI agree.

doctor --user rules

user-policy-invalid

error · The user policy does not follow the schema or cannot be read.

Without a valid user policy (~/.config/depcurfew/depcurfew.json), doctor --user cannot compare the user-level configuration with it, so only the checks that need no user policy run, as when there is none.

Fix: Fix what the message lists, or write a new user policy with depcurfew init --user --force.

user-config-unreadable

error · A user-level configuration file cannot be read, parsed or edited, or the home directory does not exist, so depcurfew cannot check it.

The package manager may still read the file (or stop on it), and its settings may weaken every project on the machine; doctor --user fails closed and reports an error instead of passing silently. Without a home directory the user files of most tools cannot be found at all.

Fix: Do what the fix of the finding says: fix invalid syntax, give read permission, replace a symlink apply --user does not write through, make a file smaller than 1 MiB, or set HOME to an existing directory.

user-config-drift

warning · needs depcurfew.json · A user-level configuration file does not match the user policy.

depcurfew apply --user writes the user policy (~/.config/depcurfew/depcurfew.json) into the user-level configuration of each installed tool, which protects every project on the machine that does not set the same settings itself, and npx, uvx and global installs. A file that no longer matches leaves that protection weaker than the policy.

Fix: Run depcurfew apply --user.

user-config-weakens

warning · A user-level configuration file has a value that weakens every project that does not set it itself.

Settings in the user-level configuration apply to every project that does not set the same key, and some apply even then (lists that tools merge across files). A value that turns the release-age delay off, exempts packages or allows install scripts or git dependencies there weakens all of them at once, and so does a file the tool reads ahead of the user file.

Fix: Remove the value from the file, or set it in the policy and run depcurfew apply --user.

user-environment-overrides

warning · An environment variable moves, skips or overrides the user-level configuration or the policy.

Package managers read settings from environment variables before their configuration files, and some variables make them read another file or none. A variable set in a shell profile or a CI runner can switch the protection off without any file showing it.

Fix: Unset the variable, or set it to a value the policy allows.

Supported tools

What depcurfew configures and checks for each tool, from its knowledge base, where every value links to the official documentation or changelog it was verified against.

⚠️ official sources disagree (depcurfew takes the safer reading) · ❓ official sources are incomplete. Every value with its source: docs/knowledge.md.

Yarn Classic (1.x) is detected but not supported.

Python projects

depcurfew configures uv, Poetry, PDM, Pipenv and pip from the same depcurfew.json, and the bots for Python packages: Dependabot pip and uv entries and Renovate.

• Detection. A Python tool counts as used when its lockfile is there, when pyproject.toml has its table, or when its own configuration file or a CI setup step shows it; requirements.txt means pip. depcurfew explain lists what it found.
• Package names. Python packages on the policy's package lists (the cooldown exceptions, installScripts.allow and installScripts.deny) take the prefix pypi:, for example "pypi:docopt". Names without a prefix stay npm names, so an exception for an npm package never applies to a Python package of the same name.
• Install scripts are builds. A wheel installs without running package code; a source distribution, a git repository or a local directory is built, which runs its build code. installScripts.default: "deny" forbids building, and the packages in installScripts.allow are the exceptions. None of the three tools can only allow a build, so these packages are always built from source, even where a wheel exists; apply says so, and doctor lists the packages in the lockfile that would be built. Packages in installScripts.deny must not be built: doctor reports one that a tool would still build (Poetry, PDM, pip and Pipenv build git, local and URL dependencies whatever their settings say), and one without wheels that cannot be installed while building is blocked.
• pip reads no project configuration. apply writes the build options into requirements.txt. The release-age delay cannot live in the project, so apply prints the environment variable to set where pip runs. doctor also checks the files a requirements file includes with -r and -c, and reports an include it cannot read.
• Lock again after apply. uv.lock records the release-age delay, and PDM checks pdm.lock against all of its resolution settings, the delay and the build ban included. After apply changes them, uv sync --locked and uv lock --check fail until you run uv lock, and pdm lock --check and pdm install --check until you run pdm lock; apply says so (lockfile-out-of-date). poetry.lock and Pipfile.lock do not depend on the settings apply writes.
• PDM and Pipenv cannot pin their own version. apply configures for the latest version depcurfew knows and names that version (version-not-pinned). Pipenv takes the delay in whole days only (rounded up), has no exceptions and no project setting that forbids building; apply says what to set where Pipenv runs instead. doctor reads pdm.lock and Pipfile.lock, and reports settings that turn the delay or the build ban off without a word: Pipenv's pure-Python resolver and PDM's uv mode.
• Hatch has no settings of its own. Its environments install with uv or pip, so a Hatch project is covered by the uv configuration (add "uv" to targets when its environments use the uv installer) or by the environment variables of pip.
• Running depcurfew. depcurfew is a Node.js program. In a project without package.json, run a pinned version with npx --yes depcurfew@<version>; in CI the GitHub Action needs nothing else.

doctor rules

Findings have a level: an error makes depcurfew doctor exit with 1, a warning or a note does not. Things doctor could not check (a binary lockfile, a lockfile format without install-script data, a missing policy) are listed as notes after the findings, not as findings. Below them, doctor says what it checked: the package managers and bots it found with the version it checked against, the files it read and every check with what it checks and its result, passed, the problems it found or skipped (checked in --json).

invalid-policy

error · depcurfew.json does not follow the schema or cannot be read.

Without a valid policy, the rules that compare the repository with depcurfew.json cannot run, so doctor runs only the rules that need no policy, as when there is no policy file.

Fix: Fix what the message lists; an editor that reads the $schema of depcurfew.json shows the problems as you type.

depcurfew-outdated

warning · The project installs a newer depcurfew than the one running.

A global install or an old cached copy may not know settings, rules or tool versions that the version pinned in the project knows, so it can miss problems or report fixed ones. The project copy is read from node_modules or package-lock.json.

Fix: Run the project's copy of depcurfew (install the project's dependencies first when only package-lock.json pins it), or update the one you run.

manager-version-too-old

error · A declared package manager version is older than a setting the repository relies on.

Package managers ignore settings they do not know yet. When packageManager, devEngines, Volta, .tool-versions or a CI step pins an older version, the setting is silently not applied there.

Fix: Raise the declared version to at least the version that introduced the setting, everywhere it is declared.

setting-ignored-by-version

error · A setting or file is ignored by the package manager version in use.

Package managers drop old settings and files in new major versions and only accept new forms from some version on. The configuration stays in the repository and looks effective while the version in use ignores it.

Fix: Move the setting to the place and form this version reads.

npmrc-overrides-policy

error · An .npmrc file changes a security setting in a way the policy does not see, or is ignored.

Package managers read .npmrc from different places with different priorities. npm ignores the .npmrc of workspace packages and the keys below a [section] header, and a before date in .npmrc takes the place of min-release-age; pnpm 10 applies a root .npmrc value whenever pnpm-workspace.yaml does not set the same setting, which can weaken the policy, and dangerously-allow-all-builds there runs every build script while pnpm-workspace.yaml has no build settings of its own.

Fix: Keep security settings out of .npmrc files that are ignored or that override the policy; set them through depcurfew.json and depcurfew apply.

pnpm-shared-workspace-lockfile

warning · pnpm 10 without a shared lockfile lets a package .npmrc change the release-age delay.

With sharedWorkspaceLockfile: false, pnpm 10 installs every workspace project separately with that project's own .npmrc layered over the workspace settings (read from the pnpm 10 source code), so a setting such as minimum-release-age=0 in a package .npmrc applies to that package.

Fix: Remove security settings from package .npmrc files, or keep the default shared lockfile.

python-config-ignored

error · A Python tool ignores a setting where it is written.

uv reads uv.toml instead of [tool.uv] when both exist, and in a workspace only the root; pip reads no configuration from the project and rejects options it does not know in requirements files; PDM in uv mode installs without only-binary; Pipenv with resolver_backend = "pure-python" locks without cool-down-period. A setting in such a place looks effective but is not, and an exclude-newer date freezes dependencies instead of delaying new versions.

Fix: Move the setting to the file the tool reads.

config-drift

error · needs depcurfew.json · A configuration file does not match what depcurfew apply writes for depcurfew.json.

A generated setting was edited by hand, or depcurfew.json changed without running depcurfew apply, so the tools enforce something other than the policy. Entries in a tool's own install-script lists that apply does not change are reported as well: one that lets a package of installScripts.deny run its scripts is an error, like the differences depcurfew apply fixes, and one that lets a package the policy does not name run them, or that blocks a package the policy allows, is a warning.

Fix: Run depcurfew apply (depcurfew apply --dry-run shows the difference), or change depcurfew.json if the edit was intended.

bot-cooldown-mismatch

error · An update bot waits less than the package manager before proposing a new version.

The bot then opens pull requests with versions the package manager would not pick yet: they fail to install where the manager re-checks the lockfile, or they bring in a version younger than the manager allows. Security updates that skip the bot delay fail the same way where the manager re-checks the lockfile. A Dependabot cooldown with an include list delays only the dependencies it names, and a Renovate packageRules entry can shorten the delay for a whole registry or update type.

Fix: Give the bot a delay at least as long as the package manager's (depcurfew apply does this).

broad-exclusion

error · An exception list matches every package, or a per-scope setting shortens the delay, which turns the protection off.

A release-age exception such as "*" (or a policy allow-list entry such as "@*/*") looks like a narrow exception but exempts every package, so the delay or the install-script block never applies. The same goes for a Renovate packageRules entry that turns minimumReleaseAge off for a whole datasource, for major, minor or patch updates of every package, or with only negative patterns, which match every package they do not name. In Yarn 4.17 and later, npmScopes.<scope>.npmMinimalAgeGate replaces the delay for one scope, so a shorter value there exempts that scope.

Fix: Replace the pattern with the packages or scopes that really need the exception.

lockfile-forbidden-source

error · needs depcurfew.json · The lockfile installs a package from a source depcurfew.json denies.

A git repository, a tarball URL or a local path bypasses the registry and its checks (release age, provenance, integrity from the registry). The lockfile shows what installs really fetch, whatever the package manager settings say.

Fix: Replace the dependency with a registry version, or allow that source in depcurfew.json.

lockfile-install-scripts

error · needs depcurfew.json · The lockfile has packages with install scripts, or Python packages built from source, that depcurfew.json does not allow.

Install scripts run arbitrary code during installation, and so does building a Python package from source (a source distribution, a git repository or a local directory). Where the package manager runs them by default, or an entry in its own allow-list lets them run, these packages execute code the policy does not allow; where it blocks them, they may not work without a build step. A package in installScripts.deny was reviewed and works without its scripts, so it is reported only while the package manager still runs them (or builds it from source), or when it cannot be installed without a build. Only npm, Bun (1.4.4+) and Deno (lockfile v5) record install scripts in the lockfile; uv.lock, poetry.lock and pylock.toml show which Python packages have no wheel.

Fix: Remove or replace the package, or review it and add it to installScripts.allow in depcurfew.json, or to installScripts.deny when it works without its scripts (Python packages with the prefix pypi:). For a package in installScripts.deny, make the package manager block its scripts (depcurfew apply records the denial where the tool can).

unreadable-config

error · A configuration file or lockfile cannot be read, parsed or edited, so depcurfew cannot check it.

A package manager or bot may still read the file and its settings may weaken the policy; depcurfew fails closed and reports an error instead of passing silently.

Fix: Fix what the message describes: invalid syntax, missing read permission, a symlink, a file over the size limit or a style depcurfew apply cannot edit.

GitHub Action

The action runs depcurfew doctor, prints the report to the job log, shows each finding as an annotation on its file and in a table in the job summary, each with how to fix it, uploads the SARIF report to code scanning and fails the job when doctor finds an error. The log and the job summary also say what was checked: the tools found, the files read and every check with its result (passed, the problems it found, or skipped because it needs depcurfew.json). A clean run adds a notice with the same list ("No problems found in 7 files for npm 11.21.1 (package.json). 13 checks: 13 passed."), so it is not mistaken for one that did nothing. Code scanning lists only alerts, so its entry stays empty when there is nothing to report; next to it, in the Checks tab of a pull request, the action adds the check "depcurfew doctor" with the result and the table of checks (it needs checks: write, which the example below grants; without it the step only says so in the log). It runs from its own checkout, with nothing to install, and sets up Node.js 22 only when the runner has an older version.

Pin it to a full commit SHA, like every action in your workflows; the example pins the commit of the latest release, and the comment names its tag. If the repository cannot use code scanning, set upload-sarif: false; the findings stay in the job log.

name: depcurfew

on:
  push:
  pull_request:

jobs:
  doctor:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      security-events: write
      # The depcurfew doctor check with the result in the Checks tab:
      checks: write
      # Only needed in private repositories:
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: DevXord/depcurfew@77ecd935be36510cae04290423cb02681080403f # v1.1.0

Other CI systems

The action works only on GitHub. On GitLab CI or any other CI, install the project's dependencies without running their install scripts, so nothing from the lockfile runs before doctor has checked it, then run the depcurfew version the lockfile pins; the job fails when doctor finds an error (exit code 1):

depcurfew:
  image: node:22
  script:
    - npm ci --ignore-scripts
    - npx --no depcurfew doctor

--no makes npx fail instead of downloading the latest depcurfew when the project does not have it; in CI npx otherwise downloads without asking. With pnpm, Yarn or Bun, use their frozen-lockfile install with install scripts turned off instead of npm ci --ignore-scripts.

depcurfew doctor --json and --sarif write the findings for other tools; set FORCE_COLOR=1 if the CI log shows colors.

Guarding installs

The configuration apply writes is what really protects a project: the package managers themselves wait out the release-age delay and refuse install scripts and sources the policy denies. depcurfew check adds a check before something is installed, which matters most for AI coding agents that add packages on their own:

npx depcurfew check zod@4 left-pad
npx depcurfew check pypi:requests "pypi:django>=5.2,<6"

For each package it looks up the npm registry (the one --registry or registry= in .npmrc names, else the public one; any other is named in a note), or PyPI for names with the pypi: prefix, and reports:

• a name the registry does not know, which is how made-up package names show up;
• a version younger than the cooldown in depcurfew.json, with the newest version that is old enough;
• install scripts the policy does not allow; for a Python package, a version without wheels, which is built from source and so runs its build code. A package in installScripts.deny is not reported, because its scripts are meant to stay blocked (doctor checks that the package manager blocks them), except a Python package without wheels, which gets a warning: it cannot be installed where building is blocked;
• a name that differs by a letter or two, or only in separators, from a popular package of its registry: 5,000 npm packages with the most weekly downloads among the results of several hundred registry searches (the npm registry has no download ranking, so a popular package can be missing), and the 5,000 most downloaded PyPI projects of a recent month;
• a deprecated version (a warning);
• a registry or index reached over plain HTTP (a warning), unless it is on this computer (localhost, 127.0.0.0/8 or ::1), such as a local registry for testing.

A registry that redirects to another origin (another host, port or scheme, so also from http:// to https:// on the same host), and one at a link-local address, where cloud metadata services answer, is not followed or asked: the package counts as not checked. For a name without a version or with a range, npm prefers the dist-tag tag= in .npmrc names, and so does check.

Python packages are written as pip takes them after the prefix (pypi:name, pypi:name==1.2, pypi:name[extra]>=1.2,<2), or as pypi:name@1.2, pypi:name@^1.2 and pypi:name@latest, as uvx and poetry add take them. The version is picked as pip picks it: the newest match, pre-releases only when asked for or when nothing else matches, and yanked versions only when pinned with == (a warning). A version is as old as its newest file, because files can be added to a release later. A project PyPI quarantines (as malware, for example) is an error; an archived or deprecated one, a warning. --index looks Python packages up in another index that serves the JSON form of the simple repository API.

Git repositories, tarball URLs and local paths are checked against the sources section only. Without a depcurfew.json in the directory or one of its parents up to the root of the repository, the default policy applies. When the registry cannot be reached, the package counts as failed: check exits with 1 whenever a package breaks the policy or cannot be checked. With --json it prints one document and nothing on stderr: packages with their findings (each with code, level, message and fix), notices, and errors for a depcurfew.json that cannot be used, in which case no package is checked.

Claude Code

depcurfew check --hook claude-code runs as a Claude Code hook before every command of the tools that run shell commands: Bash, PowerShell and Monitor. It finds the packages the command would install or download to run, checks them and answers:

• deny when a package breaks the policy (Claude sees the reason and can pick another package or version);
• ask when depcurfew cannot vouch for the command: a look-alike name, a registry it cannot reach, an error of its own, or a command it cannot read, such as one with $(...) or variables in its arguments, or a shell that runs commands from a pipe (curl … | sh);
• nothing when everything checks out, so the command goes through Claude Code's usual permission prompts.

It follows the command lines inside a command: $(...) and backticks, sh -c, PowerShell's -Command, cmd /c, eval, npx -c, yarn workspace <name>, python -m pip, the command uv run runs, a package manager run by npx, uvx or pipx run, and wrappers such as sudo, su -c, env, timeout, flock and xargs. It reads options the way each tool does, including npm's and pnpm's shorthands and abbreviations (--reg and --regis for --registry), abbreviated long options of pip and pipx (--extra for --extra-index-url) and short options with their value in the same word (-ihttps://…), so an option, or a variable such as PIP_INDEX_URL or UV_INDEX, that points the tool at another index makes it ask. It checks the version the command would install: the dist-tag --tag or npm_config_tag makes npm prefer, pre-releases that --pre, --prerelease allow and the like allow, and builds from source that the command's options or variables force (wheels refused), which count as install scripts. A script piped into an interpreter (curl … | python3, irm … | iex) or read from <(curl …) makes it ask, and so does a command with more than 50 packages, of which the first 50 are checked. deno x and dx are read like npx. Packages from requirements files (pip install -r) and the project's own files (uv sync, poetry install) are not checked, as with npm install without names; depcurfew doctor checks the lockfiles. When it cannot read the hook event at all, it exits with code 2, which blocks the command in every Claude Code version.

It reads commands the way Windows runs them too: executables in any case and with .exe, .cmd, .bat or .ps1 (NPM.CMD i lodash), paths with backslashes, and cmd /c or cmd /k (also //c from Git Bash), where %VAR% and !VAR! count as expansions. PowerShell commands (the PowerShell tool, powershell -c, pwsh -c and iex) are read like any other when they are plain commands: quotes, ;, |, &&, the call operator &, redirections and $env:NAME = "value" before a command. PowerShell syntax it does not read, such as variables, (...), $(...), {...}, @(...), backticks, commas, Start-Process or Set-Alias, makes it ask when the same statement names a package manager; a statement without one, such as Get-ChildItem | Where-Object { $_.Length -gt 1kb }, goes through. It also asks about an argument with &, |, <, > or " for a package manager run from PowerShell, because the .cmd shim of a package manager hands its arguments to cmd.exe again.

Install depcurfew as a development dependency of the project, then add the hook:

In .claude/settings.json of the project:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell|Monitor",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": [
              "${CLAUDE_PROJECT_DIR}/node_modules/depcurfew/dist/cli.js",
              "check",
              "--hook",
              "claude-code"
            ],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

The matcher Bash|PowerShell|Monitor covers every tool that runs shell commands. On Windows, PowerShell is the main shell wherever the PowerShell tool is on, and without Git Bash there is no Bash tool, so a hook on Bash alone never runs there; Monitor runs a command in the background. command is node itself, which also starts on Windows, where Claude Code runs it without a shell.

onFailure: "block" needs Claude Code 2.1.295 or later; without it, a hook that fails to start, crashes or times out lets the command through.

Commands the guard reads (an add subcommand of any npm package manager, such as install or i, is checked for all of them; Python commands are matched word for word, and python -m pip counts as pip):

The hook reads commands the way a shell splits them, but it is a safety net, not a sandbox: a command can install packages in ways it does not recognize (a script, another tool). Keep the package manager configuration from depcurfew apply in place; it is what enforces the policy for every install.

Network and privacy

Only check and the Claude Code hook use the network. For each package they request one URL with the package name in it: from the public npm registry (registry.npmjs.org) or PyPI (pypi.org), or from the registry that the project's or your .npmrc sets, --registry or --index. They send no credentials (tokens in .npmrc are not read, and a user name and password written into a registry URL are removed before the request and in every message) and nothing else about the project, and depcurfew has no telemetry. A private package whose scope has no registry in .npmrc is looked up in the public registry, so its name reaches that registry; set @scope:registry in .npmrc or pass --registry first. init, explain, apply and doctor work without network access. The GitHub Action checks the repository without it too; afterwards it sends the result (the counts, the table of checks and findings, the files read) to the GitHub API of the run (GITHUB_API_URL) with the workflow token to create the depcurfew doctor check (input check-run), and the SARIF upload to code scanning is a separate step that runs GitHub's own action. An editor that reads the $schema of depcurfew.json may download the schema from unpkg.com.

Library

The same functions are available from the package: detectProject, planApply and applyProject, runDoctor with toSarif, checkSpecs with scanCommandLine, and the policy parser and converters. Their types ship in dist/index.d.ts, and src/index.ts lists every export. The package is an ES module only: use import; require('depcurfew') works on Node.js 22.12 and later, which load ES modules with require().

Contributing

Facts about package managers live only in src/knowledge/, each with the official URL it was verified against and the date. A correction is welcome with a link to the official documentation or changelog. npm test builds the project and runs every test without network access.

License

MIT

Trademarks

npm is a registered trademark of npm, Inc. "Python" and "PyPI" are trademarks of the Python Software Foundation. pnpm, Yarn, Bun, Deno, uv, pip, Poetry, PDM, Pipenv, Renovate, Dependabot, GitHub, Claude Code and the other names in this document belong to their owners. depcurfew is an independent project and is not affiliated with or endorsed by any of them.