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