Registry & Tokens

How an install is evaluated

Every npm install (or pnpm install) request for a tarball goes through the registry proxy at https://npm.pkgpls.com, which upstreams to https://registry.npmjs.org.

• No score yet: the proxy optimistically allows the install, logs it, and enqueues scoring in the background — unless the package/version is explicitly on your org’s blocklist, in which case it’s blocked immediately even without a score.
• Scored: the proxy evaluates your org’s policy (trust/threat thresholds, allowlist, blocklist, managed rule packs, package age, malware flags) and returns one of three outcomes:
  • allow — tarball is proxied normally.
  • warn — tarball is proxied, with an X-PkgPlease-Warning response header and an npm-notice header your npm/pnpm client will print to the terminal.
  • block — a 403 response, and the tarball is never proxied. The response body includes the reason, the package’s trust/threat scores, and (if the block is “askable” — see below) a pending approval id.

Every install, regardless of outcome, is logged and shows up in the Audit Log.

Package age filtering

If your org policy sets min_package_age_days, versions newer than that are either filtered out of what the client can even see, or blocked/warned at install time — see Configuring Org Policy for the min_package_age_action setting that controls which.

Agent installs (“ask and park”)

When an agent-type token would hit a block but the block is marked askable, pkgPlease automatically files an approval request and returns its id in the 403 body instead of just failing — the agent (or the MCP approval_status tool) can poll that id until a human resolves it from the Approvals queue.

Managing credentials

From Settings:

• Service Tokens — the credential you put in .npmrc (see Getting Started). Choose scope Registry only (recommended) unless you also need to call the management API. Shown once on creation; revoke any time. A Registry only token carries just the registry audience, so calls to the management API (the endpoints in the API reference) are rejected with 403 — only a token that also includes the api audience can call those.
• Agent Credentials:
  • Provisioner tokens — paste into an agent sandbox’s MCP config as PKGPLEASE_TOKEN. A provisioner token can only mint further agent tokens — it cannot itself install packages. Revocable.
  • Agent tokens — minted automatically by a sandbox using its provisioner token; listed read-only in Settings. A token marked “Never · reduced security” does not expire — prefer letting sandboxes mint short-lived agent tokens over long-lived ones where possible.
• Slack Integration — “Add to Slack” links approval notifications and the /issue-token command (for a personal developer token) to your workspace, where available.