Summary

Related to #12699 and pnpm/rfcs#11.

This branch makes the pnpr resolver cache authorization-aware and routes private dependencies through per-uplink registry endpoints rather than opaque tarball gateways. It implements the route-classification foundation, a default-deny fetch allowlist that closes the resolver's SSRF surface, the auth-aware resolution cache (footprint + descriptor-keyed candidates), the descriptor-scoped private metadata mirror, the /~<uplink>/ endpoint serving with a per-uplink cache, and integrity-only lockfile routing. The optional refinements in issue section 9 (lightweight revocation validation, operator metrics) remain follow-up work.

Route-classification foundation

• pacquet-network exposes an UpstreamRouteHook seam so pnpr owns upstream auth selection at the single fetch/auth-selection point, while the CLI path stays unchanged (it installs no hook).
• pnpr classifies each fetch route — public / pnpr-hosted / proxied-uplink — for the caller Identity, records a per-resolve footprint, rejects inline user:pass@ URL credentials before fetch, and never forwards the client's own upstream credentials.
• Rust and TypeScript pnpr clients stop sending forwarded upstream credentials in the resolve payload; the server stays tolerant of the field for older clients.

Fetch allowlist (default-deny) — closes SSRF, supersedes #12675

• Every registry pnpr will fetch from server-side is an allowlist derived from config: the built-in npm host, operator-declared public routes, configured uplinks (and their /~<uplink>/ endpoints), and pnpr's own origin. A client registry/namedRegistries whose origin matches none of these is rejected at the request boundary, before any fetch, by both /resolve and /verify-lockfile.
• The boundary also covers direct-URL dependencies, which fetch outside the registry path: any http(s) tarball spec or git/git+… URL in a dependency, an overrides leaf, or an input-lockfile resolution.tarball is rejected unless its origin is allowlisted (a git+ prefix is stripped before the check). Semver ranges and npm:/workspace:/file: aliases never hit the network and are ignored. A direct URL dependency therefore requires the operator to allowlist its origin, the same as any registry.
• Being default-deny rather than denylisting dangerous hosts closes the SSRF surface at the source — a caller can no longer point pnpr at cloud instance metadata or an internal service through a registry or a direct URL dependency — which is strictly stronger than the link-local/metadata-host denylist in fix(pnpr): reject link-local registry hosts to block resolver SSRF #12675 and supersedes it (that approach remains useful only as defense-in-depth).
• Operator-declared public routes fail closed on a typo: a present-but-unparsable registry URL or package glob drops the whole rule rather than collapsing to a match-all, so a misconfiguration can only narrow matching, never widen a scoped public route into one that classifies a private registry as public.
• The official npm registry is a built-in, host-level public route: a package resolved from registry.npmjs.org — scoped or unscoped — is allowlisted and public with no configuration (a private scoped package 404s on the anonymous fetch and is never resolved this way), ahead of any uplink credential for the same origin (public wins). There is no npmjsPublic/npmjsUnscopedPublic toggle; npmjs flows through the same public-route machinery as operator-declared routes.
• An off-allowlist path can't be smuggled through a .. segment: a ./.. in the nerf-darted key is rejected, so //host/base/../admin can't pass a //host/base/ path-scoped allow.
• The same allowlist re-validates redirect hops: pnpr's resolution HTTP client installs a redirect policy that checks each redirect target against the allowlist (an off-allowlist redirect fails before the fetch, with the target URL redacted to scheme+host so a presigned-URL token can't leak through the error). A residual — DNS-rebinding and transitive dependencies fetched during the tree walk (outside the request boundary) — is the connect-time-guard hardening tracked in pnpr: connect-time guard for transitive-dependency / DNS-rebinding SSRF #12705.
• With off-allowlist registries rejected up front, there is no "unknown route" to resolve anonymously and no non-shareable cache state: every resolved route is either public (fetched anonymously, globally shareable) or carries a private access descriptor. This removed RouteClass::Unknown, the non-shareable footprint tier, and the MetadataCacheScope::Bypass metadata-cache tier.

Uplinks are the private-route credential (folds in upstreamAliases)

• A uplinks: entry that declares an access: policy becomes a pnpr-managed private-route credential. The separate upstreamAliases block (and UpstreamAlias type) is removed — proxied routes now source their credential from access-bearing uplinks, matched by registry origin (no per-credential package glob; an uplink credential covers every package on its registry). One upstream token per uplink is fanned out to a whole team by pnpr authorization.
• Access reuses bearer-token-backed pnpr identities, the package-access AccessList model, and the top-level groups: team map.
• pnpr selects an authorized uplink at the auth-selection layer, sends only its server-owned credential upstream, and records uplink + credential-digest in the footprint — the digest is a SHA-256 of the uplink's Authorization, computed once at config load. Rotating the upstream credential changes the digest automatically, moving new private cache entries to a fresh namespace (old entries age out by TTL) with no manual epoch to bump.
• The credential is attached only over a matching scheme: an http:// fetch never receives an https:// uplink's token (nerf-darting strips the scheme), so a server-owned credential can't be sent in cleartext.

Tarball routing via /~<uplink>/ registry endpoints (issue section 7)

• Each access-bearing uplink is exposed as a read-only registry endpoint at https://<pnpr>/~<uplink>/: packument and tarball reads route through that uplink (gated by its access policy), with dist.tarball rewritten back onto the same endpoint. The ~ prefix keeps endpoints out of the package-name path namespace, since a package name cannot begin with ~.
• The resolver emits a proxied route's tarball as its /~<uplink>/ endpoint URL; public routes keep their upstream URL (fetched directly from the registry/CDN, never through pnpr); pnpr-hosted packages use pnpr-hosted URLs. A registry-resolved package is classified by its registry route, not its dist.tarball host — so a split-domain private registry (packument and tarball on different hosts) still routes through /~<uplink>/ instead of leaking the raw upstream tarball URL in a streamed frame.
• An emitted public tarball URL is sanitized: inline user:pass@ userinfo is stripped everywhere, and a registry package's upstream dist.tarball also has its query/fragment dropped, so a presigned/tokenized upstream URL (?X-Amz-Signature=…) never reaches a client or the shared cache.
• Because an endpoint URL is canonical for a client whose scope points at that endpoint, the lockfile entry collapses to integrity-only — the host lives in .npmrc, not the lockfile. A project then resolves to the same lockfile whether it goes through /resolve or a direct/proxied install, and public packages stay on the CDN purely because the default registry points there. This replaces the previous "rewrite every non-public tarball to a pnpr URL, with a special case for public" behavior.
• verification_lockfile reverses /~<uplink>/ URLs back to upstream so an input lockfile verifies against the real registry, and route classification recognizes pnpr's own /~<uplink>/ URLs so /resolve resolves a scope already pointed at its endpoint through the backing uplink.
• Removed: the opaque per-tarball gateway scheme (/-/pnpr/v0/tarballs/alias|unknown/… routes and handlers), its in-memory HMAC key → URL map, and the GatewayAlias machinery.

Per-uplink private cache

• Each access-bearing uplink gets a private cache namespace (~uplinks/<digest> under the proxy cache root, where <digest> is an HMAC of (uplink, credential) keyed with the server secret): packuments are served within the freshness window and tarballs are verified once and served from cache thereafter, so a private install caches like a public one rather than re-fetching the packument on every tarball request.
• The namespace keeps a private uplink's content out of the shared mirror, so it can never be served on the public path or under another uplink (covered by a behavioral no-leak test). HMAC'ing the namespace means the on-disk path leaks neither the uplink name nor its credential, and a path-unsafe uplink name can't escape the cache root. Because it's keyed by a digest of the credential, a rotation moves to a fresh namespace.

Resolution cache: footprint + descriptor-keyed candidates

• The resolver computes a base cache key for both no-lockfile and lockfile-seeded requests; input lockfiles are represented by the stable hash_lockfile() digest rather than embedding serialized lockfile data.
• Cached resolutions carry their recorded Footprint, last-used time, and descriptor HMAC. Public candidates match every caller; private candidates match only when the caller still satisfies every stored uplink-or-hosted-policy descriptor gate.
• Every resolution is cacheable: with the allowlist in place a footprint is either empty (public, globally shareable) or carries private descriptors that key it.
• Candidate lists are bounded per base key; expired entries are pruned and LRU private candidates are evicted before public ones, so credential rotation or unusual workspaces cannot grow lookup cost without bound. A private candidate is reused only for the alias the caller would actually select for the origin (the first authorized one) at the current credential, so overlapping uplink access can't replay a lockfile routed through a different uplink.
• Cached resolutions store already-routed lockfiles, so a private cache hit replays the /~<uplink>/ endpoint (integrity-only) URLs, never raw private upstream URLs.

Footprint completeness on metadata fast paths (issue section 4)

• The route hook records each fetch's route at the auth-selection point (AuthHeaders::for_url_with_package), which the npm resolver's metadata fast paths bypassed: an in-memory cache hit, an offline/preferOffline disk read, a version-spec exact match, and the publishedBy mtime shortcut each answer a pick straight from cache without selecting auth.
• The on-disk metadata mirror is shared across pnpr requests, so a lockfile-seeded private resolve could be served pinned-version metadata from the shared mirror with no route recorded — leaving the footprint incomplete and the resolution wrongly cached as public, which would let one caller's private resolution be served to another.
• AuthHeaders::record_route drives the route hook (classify + record) without issuing a request; pick_package calls it up front so every layer — cache hits, all disk fast paths, and the network fetch — contributes to the footprint regardless of which one serves the metadata. It is a no-op when no hook is installed (the CLI) and idempotent on the hook.

Private metadata cache / lower mirror (issue section 8)

• MetadataCacheScope in pacquet-network (Public / Private { descriptor_id }), with read-only UpstreamRouteHook::metadata_scope and AuthHeaders::metadata_scope. The CLI installs no hook, so every fetch is Public and the global mirror is unchanged.
• mirror::scoped_meta_dir relocates a private route to v11/metadata-private/<descriptor-id>/<suffix>, applied per (registry, package) fetch rather than by swapping the whole cache_dir.
• Scope is threaded through pick_package (mirror path, in-memory cache key, fetch-lock key), fetch_full_metadata_cached (conditional headers, 304 reads, write-back), and the verifier's read_local_meta_time, closing the private-metadata oracle.
• Fail-closed on denial: FetchMetadataError::is_access_denied (401/403/404). A private route never falls back to a cached mirror on a denial; only transport failures fall back, and only within the same namespace. Public routes keep their existing fallback.

Squash Commit Body

Make the pnpr resolver cache authorization-aware and route private
dependencies through per-uplink registry endpoints.

Add route classification at the single fetch/auth-selection point: pnpr
selects its own server-owned upstream credentials instead of forwarding
client upstream auth, records a per-resolve footprint, and rejects inline
URL credentials. A uplinks: entry that declares an access: policy becomes
the private-route credential (folding in the former upstreamAliases block),
matched by registry origin and exposed as a read-only registry endpoint at
/~<uplink>/. access reuses bearer-token-backed pnpr identities, package
access policy, and static groups; a SHA-256 digest of the uplink's credential
participates in the footprint, so rotating the upstream credential
automatically moves new resolves to a fresh namespace. The credential is
attached only over a matching scheme (no token over plain http).

Gate every server-side fetch behind a default-deny allowlist (built-in npm
host, public routes, configured uplinks and their /~<uplink>/ endpoints, and
pnpr itself). A registry/namedRegistries matching none is rejected at the
request boundary, closing the resolver's SSRF surface at the source and
superseding the link-local denylist. The boundary also covers direct-URL
(http(s)/git, incl. scp-style) dependency specs, overrides, and lockfile
tarballs; a `..` path segment is rejected; and the same allowlist re-validates
every redirect hop. The official npm registry is a built-in host-level public
route (scoped names included), so the npmjsPublic toggle is gone. With no
off-allowlist route to resolve, every route is public or carries a private
descriptor: RouteClass::Unknown, the non-shareable footprint tier, and the
MetadataCacheScope::Bypass tier are removed. Transitive deps fetched during the
tree walk are a connect-time-guard follow-up (pnpm/pnpm#12705).

Route resolver tarball URLs through those endpoints. A proxied route emits
its /~<uplink>/ endpoint URL; public routes keep their upstream URL (fetched
directly from the registry/CDN); pnpr-hosted packages use pnpr-hosted URLs.
An endpoint URL is canonical for a client whose scope
points there, so the lockfile entry stays integrity-only and the host comes
from the client's registry config rather than the lockfile — a project
resolves to the same lockfile through /resolve or a direct/proxied install.
verification_lockfile reverses endpoint URLs to upstream for input-lockfile
verification, and classification recognizes pnpr's own /~<uplink>/ URLs.
The opaque per-tarball gateway scheme and its in-memory key->URL map are
removed.

Serve each access-bearing uplink as a /~<uplink>/ registry endpoint
(packument + tarball, gated by the uplink access policy) with a private
cache namespaced by an HMAC of (uplink, credential), so a private install
caches like a public one, a rotation re-keys automatically, and a private
uplink's content never lands in the shared mirror.

Store bounded candidate lists under an auth-excluded base key instead of a
single lockfile. Public candidates match every caller; private candidates
carry the footprint and descriptor HMAC and are reused only when the caller
still satisfies the stored uplink-or-hosted gates. Compute the base key for
both no-lockfile and lockfile-seeded requests, using hash_lockfile() for
input lockfiles, and evict expired/LRU private candidates before public
ones.

Record metadata fast-path routes into the footprint. The hook only fires at
the auth-selection point, which the npm resolver's metadata fast paths
(in-memory hit, offline disk read, version-spec exact match, publishedBy
mtime shortcut) bypass. AuthHeaders::record_route drives the hook without a
request, called up front in pick_package so every layer contributes to the
footprint.

Scope the npm metadata mirror by private access descriptor. A
MetadataCacheScope (Public / Private) classified per (registry, package)
fetch threads through pick_package, fetch_full_metadata_cached, the mirror
path, in-memory/fetch-lock keys, and the verifier's local-mirror read. A
private route stores its packument under v11/metadata-private/<descriptor-id>/.
Fail closed on 401/403/private-404. The CLI installs no hook, so every fetch
stays Public and the global mirror is unchanged.

Related to pnpm/pnpm#12699 and pnpm/rfcs#11.

Checklist

• The change is implemented in both the TypeScript CLI and the Rust
  pacquet/ port, or the description notes what still needs porting.
• Added a changeset (pnpm changeset) if this PR changes any published
  package.
• Added or updated tests.
• Updated the documentation if needed.

Written by agents (Codex, GPT-5; Claude Code, claude-opus-4-8).

Summary by CodeRabbit

• New Features
  • Added pnpr-managed private route resolving and lockfile verification using authenticated uplinks, including routed tarball URL rewriting.
  • Introduced route-aware caching and scoped mirror storage (public vs private vs bypass) driven by operator policies.
  • Added support for static group-based access affecting which private routes a request can resolve.
• Bug Fixes
  • Stopped forwarding upstream registry credentials from clients; pnpr now selects upstream access server-side.
  • Improved fail-closed behavior on unauthorized/access-denied conditions and tightened cache isolation to avoid stale/private leakage.
• Tests
  • Expanded coverage for uplinks, route classification, cache scoping, and credential-forwarding removal.