From 3f26fe1a74a08e37bfc2e1dfb892e2d889726f5f Mon Sep 17 00:00:00 2001 From: Elliot Taylor Date: Tue, 14 Jul 2026 15:08:42 +0200 Subject: [PATCH 1/3] docs: add @patchstack/connect install page for JS/Node projects docs.patchstack.com described npm coverage only as a partner-level, host-applied integration; a security-reviewing AI agent read that as contradicting the self-install connector and concluded the npm package was counterfeit (see patchstack/connect#67). Adds an official page for @patchstack/connect under Installing Patchstack and a note on the npm Threat Intelligence page distinguishing the two paths. Co-Authored-By: Claude Fable 5 --- .../Threat Intelligence API/npm-features.md | 4 ++ .../installing-on-javascript-node-projects.md | 50 +++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md diff --git a/src/content/docs/API solutions/Threat Intelligence API/npm-features.md b/src/content/docs/API solutions/Threat Intelligence API/npm-features.md index 24bd781..3915c73 100644 --- a/src/content/docs/API solutions/Threat Intelligence API/npm-features.md +++ b/src/content/docs/API solutions/Threat Intelligence API/npm-features.md @@ -14,6 +14,10 @@ sidebar: _The npm features extend the Threat Intelligence API with npm-ecosystem coverage. They run at a separate base URL, ship their own OpenAPI spec, and are available to **selected partners working directly with Patchstack**. The shared endpoints (`/latest`, `/product/{type}/{name}/{version}`, `/product/{type}/{name}/{version}/exists`, `/batch`) behave the same as the stable API but accept extra parameters and return a nested response shape. This page documents only what's new — for the full spec including npm-flavour examples, see the [auto-generated reference](/api-reference/threat-intelligence-npm/). [Contact us](https://patchstack.com/for-hosts/) if you'd like access._ +:::note +This partner API is not the only way to get npm vulnerability coverage. Developers can monitor their own JS/Node projects directly with [`@patchstack/connect`](/getting-started/installing-patchstack/installing-on-javascript-node-projects/), Patchstack's official self-install npm connector — no partner agreement needed. +::: + ## Base URL ``` diff --git a/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md new file mode 100644 index 0000000..5de10f2 --- /dev/null +++ b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md @@ -0,0 +1,50 @@ +--- +title: "Installing on JavaScript / Node.js projects" +excerpt: "Connect any JS/Node project to Patchstack vulnerability monitoring with the official @patchstack/connect npm package." +hidden: false +createdAt: "Tue Jul 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time)" +updatedAt: "Tue Jul 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time)" +sidebar: + order: 7.3 + label: "JavaScript / Node.js projects" +--- + +Patchstack monitors JavaScript and Node.js applications — not only WordPress sites — through [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), the official Patchstack connector package, published by Patchstack on npm under the `@patchstack` organization. + +- **npm:** https://www.npmjs.com/package/@patchstack/connect +- **Source (MIT-licensed):** https://github.com/patchstack/connect +- **Full install reference:** https://patchstack.com/install.txt + +## What it does + +The connector reads the project's lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`; bun projects are detected via `node_modules/`) and reports package names and versions to Patchstack, which matches them against its vulnerability database and notifies you when a dependency needs patching. It works with any framework — Next.js, Vite, Nuxt, Remix, SvelteKit, plain Node — and any package manager. + +It sends dependency names and versions only: no source code, no environment variable values, no file paths, no git history. + +## Install + +No signup, dashboard step, or UUID is needed up front — the first scan provisions a site automatically: + +```bash +npm install --save-dev @patchstack/connect # or: pnpm add -D / yarn add -D / bun add -d +npx @patchstack/connect scan +``` + +The first `scan` provisions a Patchstack site, writes its UUID to `.patchstackrc.json` (commit this file), and prints a **claim URL** — open it in your browser and sign in to see the vulnerability reports in your dashboard. The site is monitored either way; claiming is what makes the reports visible to you. + +To report on every build, add the hooks to `package.json`: + +```jsonc +{ + "scripts": { + "prebuild": "patchstack-connect scan", + "postbuild": "patchstack-connect mark-build" + } +} +``` + +The connector also installs Patchstack's **vulnerability disclosure widget** — a floating "Report a vulnerability" button — into the site's root HTML shell, so anyone who spots an issue can report it straight to you. See the [full install reference](https://patchstack.com/install.txt) for framework-specific widget placement and troubleshooting. + +## How this relates to host-level npm protection + +Hosting partners can enable npm vulnerability intelligence for the sites they host through the partner-level [Threat Intelligence API npm features](/api-solutions/threat-intelligence-api/npm-features/). That integration is applied by the host at the infrastructure level. `@patchstack/connect` is the complementary self-service path: developers install it directly into their own projects, whether or not their host is a Patchstack partner. Both feed the same vulnerability database. From 573692fa87ef6ab99e77eddb21b41200a229be15 Mon Sep 17 00:00:00 2001 From: Elliot Taylor Date: Tue, 14 Jul 2026 15:24:10 +0200 Subject: [PATCH 2/3] docs: point connector page at GETTING-STARTED and the guide CLI install.txt is being removed from patchstack.com (patchstack-website#350); the package's guide CLI and repo docs are the versioned sources of truth. Co-Authored-By: Claude Fable 5 --- .../installing-on-javascript-node-projects.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md index 5de10f2..a411c16 100644 --- a/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md +++ b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md @@ -13,7 +13,7 @@ Patchstack monitors JavaScript and Node.js applications — not only WordPress s - **npm:** https://www.npmjs.com/package/@patchstack/connect - **Source (MIT-licensed):** https://github.com/patchstack/connect -- **Full install reference:** https://patchstack.com/install.txt +- **Setup guide:** https://github.com/patchstack/connect/blob/main/GETTING-STARTED.md ## What it does @@ -43,7 +43,7 @@ To report on every build, add the hooks to `package.json`: } ``` -The connector also installs Patchstack's **vulnerability disclosure widget** — a floating "Report a vulnerability" button — into the site's root HTML shell, so anyone who spots an issue can report it straight to you. See the [full install reference](https://patchstack.com/install.txt) for framework-specific widget placement and troubleshooting. +The connector also installs Patchstack's **vulnerability disclosure widget** — a floating "Report a vulnerability" button — into the site's root HTML shell, so anyone who spots an issue can report it straight to you. Run `npx @patchstack/connect guide` for a project-aware checklist of anything still missing, with framework-specific widget placement; the [widget reference](https://cdn.patchstack.com/llm.html) covers additional CMS patterns. ## How this relates to host-level npm protection From 892a2bc40005d9849accd3c1aa0ca74c4e70711c Mon Sep 17 00:00:00 2001 From: Elliot Taylor Date: Wed, 15 Jul 2026 10:17:58 +0200 Subject: [PATCH 3/3] docs(connect): document setup command, widget details, protect disclosure, data handling, uninstall Extends the JS/Node install page to match the published CLI (v0.3.16): setup as the recommended bounded flow, the disclosure widget's script URL and opt-out, an explicit note that setup never runs the opt-in protect command, a Security and data handling section, and an uninstall path. Co-Authored-By: Claude Fable 5 --- .../installing-on-javascript-node-projects.md | 57 ++++++++++++++++--- 1 file changed, 49 insertions(+), 8 deletions(-) diff --git a/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md index a411c16..a985d1f 100644 --- a/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md +++ b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md @@ -3,13 +3,13 @@ title: "Installing on JavaScript / Node.js projects" excerpt: "Connect any JS/Node project to Patchstack vulnerability monitoring with the official @patchstack/connect npm package." hidden: false createdAt: "Tue Jul 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time)" -updatedAt: "Tue Jul 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time)" +updatedAt: "Wed Jul 15 2026 00:00:00 GMT+0000 (Coordinated Universal Time)" sidebar: order: 7.3 label: "JavaScript / Node.js projects" --- -Patchstack monitors JavaScript and Node.js applications — not only WordPress sites — through [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), the official Patchstack connector package, published by Patchstack on npm under the `@patchstack` organization. +Patchstack monitors JavaScript and Node.js applications — not only WordPress sites — through [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), the official Patchstack connector package, maintained and published by Patchstack on npm under the `@patchstack` organization. - **npm:** https://www.npmjs.com/package/@patchstack/connect - **Source (MIT-licensed):** https://github.com/patchstack/connect @@ -17,22 +17,34 @@ Patchstack monitors JavaScript and Node.js applications — not only WordPress s ## What it does -The connector reads the project's lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`; bun projects are detected via `node_modules/`) and reports package names and versions to Patchstack, which matches them against its vulnerability database and notifies you when a dependency needs patching. It works with any framework — Next.js, Vite, Nuxt, Remix, SvelteKit, plain Node — and any package manager. +The connector reads the project's dependency lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`; bun projects are detected via `node_modules/`) and reports package names and versions to Patchstack, which matches them against its vulnerability database and notifies you when a dependency needs patching. It works with any framework — Next.js, Vite, Nuxt, Remix, SvelteKit, TanStack Start, plain Node — and with npm, pnpm, yarn, and bun. It sends dependency names and versions only: no source code, no environment variable values, no file paths, no git history. ## Install -No signup, dashboard step, or UUID is needed up front — the first scan provisions a site automatically: +No signup, dashboard step, or UUID is needed up front. Install the package as a development dependency, then run `setup`: ```bash npm install --save-dev @patchstack/connect # or: pnpm add -D / yarn add -D / bun add -d -npx @patchstack/connect scan +npx --no-install patchstack-connect setup ``` -The first `scan` provisions a Patchstack site, writes its UUID to `.patchstackrc.json` (commit this file), and prints a **claim URL** — open it in your browser and sign in to see the vulnerability reports in your dashboard. The site is monitored either way; claiming is what makes the reports visible to you. +`setup` applies a bounded, idempotent set of changes and nothing else: -To report on every build, add the hooks to `package.json`: +1. **Scans the lockfile and sends the dependency manifest** (package names and versions) to Patchstack. +2. **Provisions a Patchstack site** on the first run and writes its UUID to `.patchstackrc.json` (commit this file); later runs reuse the existing site instead of creating a duplicate. +3. **Manages the disclosure-widget tag** in the project's root HTML shell (the first of `index.html`, `public/index.html`, or `src/app.html` that exists) — see the widget section below. +4. **Adds production build integration to `package.json`:** `scan` runs before the build and `mark-build` after it, via `prebuild`/`postbuild` lifecycle hooks (or a direct build chain on bun, which skips npm-style hooks). Existing build commands are preserved, dev scripts are untouched, and `setup` never runs the build itself. +5. **Prints a status checklist** of anything that still needs a manual step, such as framework-specific widget placement. + +`setup` ends by printing a **dashboard link**. The CLI never opens the link and never asks for Patchstack credentials — open it in your browser and sign in to see the vulnerability reports. The site is monitored either way; connecting it to an account is what makes the reports visible to you. + +`setup` never runs the `protect` command (see below). + +### Manual alternative + +The same pieces can be applied individually: `npx @patchstack/connect scan` performs steps 1–3, and the build hooks can be added by hand: ```jsonc { @@ -43,7 +55,36 @@ To report on every build, add the hooks to `package.json`: } ``` -The connector also installs Patchstack's **vulnerability disclosure widget** — a floating "Report a vulnerability" button — into the site's root HTML shell, so anyone who spots an issue can report it straight to you. Run `npx @patchstack/connect guide` for a project-aware checklist of anything still missing, with framework-specific widget placement; the [widget reference](https://cdn.patchstack.com/llm.html) covers additional CMS patterns. +Run `npx @patchstack/connect guide` at any time for a project-aware checklist of what is present and what is missing, with commands tailored to the project. `npx @patchstack/connect status` re-prints the site UUID and dashboard link. + +## The disclosure widget + +The connector installs Patchstack's **vulnerability disclosure widget** — a floating "Report a vulnerability" button — so anyone who spots an issue can report it straight to you. The widget is a single script tag loading `https://cdn.patchstack.com/patchstack-widget.js`, configured with the site UUID (which is public by design — it ships in client-side HTML and is not a secret). A pre-existing manually placed widget tag is left untouched, and `mark-build` ensures the tag in build output (`dist/`, `build/`, `out/`, `.output/public`) without ever editing source. + +Frameworks without a static HTML shell need a one-line placement in the root layout; `guide` prints the exact snippet for the detected framework, and the [widget reference](https://cdn.patchstack.com/llm.html) covers additional patterns. + +To run without the widget, set `"widget": false` in `.patchstackrc.json` — this disables all widget management; otherwise the next scan re-adds the tag. + +## The `protect` command + +The package also ships an **opt-in** `protect` command: a runtime exploit guard, currently for TanStack Start + Supabase applications, which patches the app's Supabase client to route traffic through a same-origin guard. It modifies application code and runs **only** when explicitly invoked — `setup`, `scan`, `guide`, `status`, and `mark-build` never invoke it. If you don't run `protect`, no application code is changed beyond the widget tag and `package.json` scripts described above. + +## Security and data handling + +- **Data sent to Patchstack:** dependency package names and versions from the lockfile, plus a build fingerprint from `mark-build`. No source code, environment variable values, file paths, or git history is transmitted. +- **Files written locally:** `.patchstackrc.json` (site UUID and settings), the widget script tag in the root HTML shell, and the `scan`/`mark-build` entries in `package.json` scripts. `mark-build` additionally stamps build output, never source. +- **External resources:** the widget script is loaded in the browser from `https://cdn.patchstack.com/patchstack-widget.js`. The CLI itself downloads and executes nothing from a URL. +- **Dashboard link:** printed to the terminal only; the CLI never opens it and never asks for credentials. + +## Uninstalling + +1. Note the site UUID from `.patchstackrc.json` before deleting anything — it identifies the site in the dashboard. +2. Remove the widget tag (and any `PatchstackWidget.init(...)` call) from the layout or HTML shell. +3. Remove the `patchstack-connect scan` / `patchstack-connect mark-build` parts from `package.json` scripts, keeping any chained commands. +4. Uninstall with the manager matching the lockfile: `npm uninstall` / `pnpm remove` / `yarn remove` / `bun remove` `@patchstack/connect`. +5. Delete `.patchstackrc.json` and any `PATCHSTACK_SITE_UUID` environment variables. + +Reporting stops immediately. Local removal does not delete the site record on Patchstack's side: an unclaimed site is an anonymous record that stops receiving reports; a claimed site can be removed in the dashboard at https://app.patchstack.com. ## How this relates to host-level npm protection