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 matches a live entry in your org’s org-blocks pack, in which case it’s blocked immediately even without a score.
• Scored: the proxy evaluates your org’s policy — see Configuring Org Policy for the full precedence order (security blocks, policy blocks, endorsements, managed rule packs, warn tiers) — 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. The npm-notice header carries the same reason and scores in one line, plus whether the block is askable. It describes state only: the registry’s main caller is an agent, so the notice never points at a dashboard or any other override an agent cannot perform — for an askable block it names the request_approval / approval_status MCP tools instead.

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.

When the metadata request resolves to an older version than npm’s latest, an npm-notice header says which version was served and why the newer one was not.

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.

The MCP server that provides approval_status is @pkgplease/agent — see Agent Setup (MCP Server) for how to install and configure it.

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 — split into two tabs, Provisioning Tokens (default) and Agent Tokens:

  • Provisioning Tokens — mint a provisioner (“Issue provisioning token”) and export it as PKGPLEASE_PRV_TOKEN in your shell profile (or pkgpls token create --type provisioner mints and prints one for you). A provisioner token can only mint further agent tokens — it cannot itself install packages. Revocable from this tab.
  • Agent Tokens — minted automatically by a sandbox using its provisioner token; listed read-only, with no control to mint one by hand. A token marked “Never · reduced security” does not expire — prefer letting sandboxes mint short-lived agent tokens over long-lived ones where possible.

  For the full provisioner-to-agent-token flow, and how the credential ends up in .npmrc, see Agent Setup (MCP Server).

• Slack Integration — “Add to Slack” links approval notifications and the /issue-token command (for a personal developer token) to your workspace, where available.