rfc(pnpr): package screening and verdict store

[zkochan]

Summary

Proposes a screening layer for artifacts pnpr serves (aligned with the registries rename after #16):

• Verdict store — signed, append-only analysis verdicts keyed by tarball integrity (not name@version, not registry), so identical bytes share analysis across registries and signed verdict bundles can be exchanged between deployments later.
• Analyzer pipeline — advisory lookup (OSV, exists today), deterministic static capability analysis (always full-artifact), and an optional AI review agent.
• Incremental AI review — new versions are reviewed as a normalized diff against the last verified version, with mandatory escalation to full review (diff size, periodic re-anchoring, install-script changes, new binaries, publisher change). Prompt injection and boiling-frog diff-splitting are treated as first-class threats: worst-verdict-wins, an AI "clean" can never lift a static/advisory finding, and reviewer-directed instructions in package content are themselves a finding.
• Per-registry policy — cooldown for freshly published versions (registry-side minimumReleaseAge), hold/block as explicit 403 with machine-readable reason (never 404, to prevent fall-through), publish-time scanning on hosted registries, operator dispositions, and post-serve revocation surfacing.

Independent of, but composable with, the patch-provider RFC (#14): a block reason can advertise an available patched artifact when a patch manifest knows one.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 53f836a9-82b7-4f64-bb82-c2a96fa950d6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rfc/pnpr-package-screening

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-free-for-open-source-projects]

PR Summary by Qodo

RFC: Package screening pipeline and content-addressed verdict store

📝 Documentation 🕐 20-40 Minutes

AI Description

• Define a per-artifact screening pipeline (advisory, static, optional AI) for pnpr-served packages.
• Specify a signed, append-only verdict store keyed by tarball integrity for cross-mount reuse.
• Describe per-mount enforcement (cooldown, hold/block 403) and incremental AI review escalation
 rules.

Diagram

graph TD
  C["Client (pnpm/npm)"] --> S["pnpr server"] --> P["Analyzer pipeline"] --> V[("Verdict store")]
  S --> M["Mount policy"] --> D{Decision}
  D -->|"serve"| R["200 + tarball/packument"]
  D -->|"hold/block"| F["403 + reason"]
  S --> U{{"Upstream/Hosted registry"}} --> S

  subgraph Legend
    direction LR
    _svc["Service"] ~~~ _db[("Store")] ~~~ _ext{{"External"}} ~~~ _dec{"Decision"}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Key verdicts by unpacked content digest (plus tarball integrity)

• ➕ Deduplicates analysis across repacked-but-identical tarballs (different gzip headers, re-tarring).
• ➕ Moves the identity closer to what analyzers actually inspect (file tree + bytes).
• ➖ Requires canonical unpacking + hashing rules to avoid ambiguity and performance regressions.
• ➖ May complicate integrity-based linkage back to registry metadata and caching layers.

2. Sigstore/in-toto attestations with a transparency log

• ➕ Standard ecosystem primitives for signing and verification; easier cross-org sharing.
• ➕ Transparency log reduces key-trust fragility and helps detect equivocation.
• ➖ More infrastructure and operational complexity than an on-disk local verdict store.
• ➖ Harder to ship incrementally; adds external dependencies or new services.

3. External decision API as the primary screening mechanism

• ➕ Offloads analysis cost and rule maintenance to a specialized vendor/service.
• ➕ Can provide fast ecosystem-wide signals (campaign tracking, reputation).
• ➖ Runtime dependency risk; outages become install outages unless failing open.
• ➖ Inventory/privacy concerns (dependency graph leaks) and less local-first control.

Recommendation: The RFC’s core approach (content-addressed, append-only signed verdicts + per-mount policy + worst-verdict-wins composition) is a strong baseline that supports incremental rollout (cooldown/advisory/static before AI). The most valuable refinement to consider early is recording an additional unpacked-tree digest alongside tarball integrity to capture repack equivalence, while keeping integrity as the primary lookup key for registry correctness. Sigstore/transparency-log integration is best treated as a later evolution once verdict exchange becomes a concrete requirement.

Files changed (1) +349 / -0

Documentation (1) +349 / -0

0000-package-screening.mdAdd RFC for screening pipeline, incremental AI review, and verdict store +349/-0

Add RFC for screening pipeline, incremental AI review, and verdict store

• Introduces an RFC proposing artifact screening in pnpr via a pipeline of advisory, static capability, and optional AI analyzers. Defines a signed, append-only verdict store keyed by tarball integrity, plus per-mount enforcement semantics (cooldown and explicit 403 hold/block) and incremental AI review escalation rules designed for prompt-injection and slow-drip attacks.

pnpr/text/0000-package-screening.md

[owlstronaut]

hey @zkochan ! I've been looking into this, and 403 plus a reason body isn't enough today, because the client throws the body away before anything can render it.

FetchError keeps only {status, statusText}, so nothing downstream ever sees the body. The 403 is reported as an auth error, telling the user to run pnpm login

Since 403 already means "log in", the client could use something in the body to recognize a policy block. It could be the same { name, version, code, reason} that pnpr's violations frame already emits.

Happy to implement the client side if that's a direction you want. Separately, we could also add parity with npm's policyRestrictions which clearMeta currently drops (though i realize it being there isn't necessarily a reason to adopt it.

For context: I'm a former npm CLI maintainer, still working in this space, and I have interest in seeing this feature work well 😄