Security

#Verification order

jup accepts an artifact through the first suitable check:

If none applies, installation fails. Set JUP_REQUIRE_SIGNATURES=1 to reject the third option. An explicit project digest remains enough because it is the project's independent expected value.

Hashing covers the compressed artifact bytes as downloaded. A mismatch leaves nothing installed.

#Native and host-specific tools

Some tools publish a different artifact for each host. Their exact manifest pin has no portable digest. jup verifies the current host's registry signature and stores the checked digest in local state. A range lockfile may record separate integrity values for each host.

Unsupported operating systems, architectures, or release targets are rejected before a download starts.

#Protect the store

JUP_HOME contains executable code, global defaults, downloaded trust keys, and shim backup records. Treat it like an installed program directory:

• keep it owned and writable only by the right user;
• restore CI caches only from trusted jobs;
• do not share it with untrusted forks;
• do not copy unknown files into it;
• use the same home when enabling and disabling shims, so restoration records stay available.

A project env file is not allowed to choose JUP_HOME or a shim directory. Process-level environment settings can.

On a store hit, jup trusts its completed marker. It does not rehash every installed file before every command. This keeps startup fast, but means local store modification is equivalent to modifying an installed executable.

#Project configuration limits

A repository can choose its package manager, version, and eligible registry routing. It cannot use .jup.env to provide:

• credentials;
• trust-key changes or verification opt-outs;
• custom CA files or disabled TLS;
• JUP_HOME or shim paths;
• unsafe URL permission;
• spec-file overrides or host runtimes.

A project .npmrc can choose a registry, but its credentials and TLS settings are ignored. User and global .npmrc files may provide them.

These limits reduce risk; they do not make running an unknown repository safe. A selected package manager still executes code and may install project packages with lifecycle scripts of its own.

#Network protections

jup:

• verifies TLS by default;
• scopes credentials to their configured origin and path;
• drops authorization on cross-origin redirects;
• redacts URL user information from messages;
• refuses an artifact URL on the wrong registry host;
• caps redirects, JSON sizes, retries, archive entries, and extracted bytes.

The archive extractor rejects escaped paths, links, devices, FIFOs, and unsafe file modes. The final install appears through an atomic rename only after checks complete.

#Trust-key updates

jup includes npm trust keys. When npm rotates to an unknown key ID, jup may fetch an updated key list from npm's official key endpoint and cache it under JUP_HOME. A custom JUP_INTEGRITY_KEYS value replaces the built-in store and disables that automatic refresh.

A valid old package signed by a matching expired key is accepted only with an advisory. A bad signature is still rejected.

#Dangerous overrides

Use these only as short, process-scoped exceptions:

JUP_ALLOW_UNVERIFIED=1 jup use <tool>@<version>
JUP_INTEGRITY_KEYS=0 jup cache install
JUP_STRICT_SSL=0 jup cache install
JUP_ENABLE_UNSAFE_CUSTOM_URLS=1 jup <tool>@https://example/artifact.tgz

• JUP_ALLOW_UNVERIFIED=1 permits an artifact with no verification and warns.
• JUP_INTEGRITY_KEYS=0 or an empty value disables registry signature verification; unpinned artifacts still require the explicit unverified opt-out.
• JUP_STRICT_SSL=0 disables TLS verification and warns when used.
• JUP_ENABLE_UNSAFE_CUSTOM_URLS=1 lets a known tool name use a custom URL. Pin the URL bytes with a supported hash fragment.

Do not put these in shell profiles or repositories. Project env files cannot set them.

#Offline archives

Import uses the same safe extraction rules and validates the jup archive layout. An archive is still input from whoever sent it. Authenticate the transfer or verify a separately published signature/checksum. Network-disabled mode does not prove an archive is trustworthy.

#When a check fails

Do not paste an unexpected “got” digest into the project just to make the error go away.

See Troubleshooting for error-specific steps.