@patchstack/connect 0.3.17 → 0.3.19

package/AGENT-INSTALL.md

@@ -9,6 +9,8 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 - **`scan` makes one source edit, and only after a successful post:** it adds (or updates) the disclosure widget's `<script>` tag in the project's root HTML shell — the first of `index.html`, `public/index.html`, or `src/app.html` that exists. It touches no other file, never edits on `--dry-run` or after a failed post, leaves any pre-existing manual widget tag untouched, and is disabled entirely by `"widget": false` in `.patchstackrc.json`. `mark-build` writes to build output only (`dist/`, `build/`, `out/`, `.output/public`), never to source. `guide`, `status`, and `init` write nothing except `init`'s own `.patchstackrc.json`.
 - **`setup` runs `scan`, then edits only `package.json` build scripts:** it preserves existing commands, adds `scan` before builds and `mark-build` after builds, and uses a direct build chain for Bun. It never runs the project build or `protect`. If the widget needs a framework-specific source edit, it prints the exact remaining step instead of rewriting framework code.
 - The package also bundles an **opt-in** `protect` command (runtime exploit guard; its templates live under `dist/protect/`). It runs **only** when explicitly invoked; `scan`, `setup`, `guide`, `status`, and `mark-build` never invoke it, and it writes only local files. It auto-wires known stacks — **TanStack Start + Supabase** (patches the Supabase client + `src/start.ts`), **Next.js** (scaffolds `middleware.ts`), **SvelteKit** (`src/hooks.server.ts`), **Astro** (`src/middleware.ts`), **NestJS** (`app.use(patchstackMiddleware)` in the bootstrap), **Fastify** (`app.register(patchstackFastify)`), and **Express** (`app.use(patchstackMiddleware)`). On **any other stack** it scaffolds a framework-agnostic guard under `src/patchstack/` and prints a wiring plan — then you finish the install by importing that guard into your server entry (`protectFetch(handler)` for a Web-Fetch server, or `app.use(patchstackMiddleware)` for Node/Express) and running `patchstack-connect protect --check` to confirm it is wired (exit 1 until it is). Passing `--demo` seeds a broad sample rule set (for demonstrations, not production).
+- **`demo node-serialize` is an explicit production-backed walkthrough.** It requires `node-serialize@0.0.4` to already be present in the lockfile; it does not install the vulnerable dependency. It runs the same production `scan`, polls the configured site's public Pulse rules endpoint until rule `18843` is served, runs `protect`, verifies the generated guard, and prints exploit/benign test requests. It writes the same manifest/widget and guard files as those underlying commands. It does not start/restart the app and does not send the printed requests.
+- **`demo-guide node-serialize` is the read-only companion.** It checks the Host-created site configuration and vulnerable lockfile entry, explains the complete local prepare/run/restart/prove/cleanup sequence, and prints the next exact command. It does not require a deployment and does not change files or contact Patchstack.
 - Patchstack is not WordPress-only. This connector monitors any JS/Node project — Vite, Next.js, plain vanilla JS, anything with a lockfile.
 
 ## Before you start — never install twice

package/README.md

@@ -62,16 +62,26 @@ patchstack-connect guide                           Show this project's setup sta
                                                    what's missing, with tailored commands), then
                                                    print the full setup guide
 patchstack-connect protect                         Opt-in: install the always-on runtime exploit
-                                                   guard (currently TanStack Start + Supabase; it
-                                                   patches the app's Supabase client to route
-                                                   traffic through a same-origin guard). Never
-                                                   run by scan/setup/guide/mark-build.
+                                                   guard. Auto-wires supported server stacks;
+                                                   use --check to verify or --demo for local rules.
+                                                   Never run by scan/setup/guide/mark-build.
+patchstack-connect demo node-serialize             Production-backed walkthrough: require
+                                                   node-serialize@0.0.4, scan it, wait for live
+                                                   rule 18843, install + verify the runtime guard,
+                                                   and print exploit/benign test requests.
+patchstack-connect demo-guide node-serialize       Read-only, state-aware instructions for the
+                                                   local demo, including the next exact command,
+                                                   expected proof, and cleanup.
 patchstack-connect help                            Print help
 
-Options (for scan and status):
+Options (for scan, setup, and status):
   --site-uuid <uuid>      Override the configured site UUID
   --endpoint <url>        Override the API endpoint
   --dry-run               (scan only) Print the payload without posting
+
+Options (for demo and demo-guide):
+  --url <url>             Test endpoint printed at the end
+                          (default: http://localhost:3000/api/tasks)
 ```
 
 ## Configuration
@@ -101,6 +111,27 @@ Environment variables:
 
 The site UUID identifies the site; it is not a secret — the disclosure widget ships the same UUID in client-side HTML, and committing `.patchstackrc.json` is the intended workflow so every developer and CI run reports to the same site. Possession of the UUID lets someone submit dependency manifests for that site (noise, not data access). In CI setups where the file isn't committed, set `PATCHSTACK_SITE_UUID` instead.
 
+## Production virtual-patch demo
+
+The `node-serialize` scenario demonstrates dependency detection and a live, version-scoped virtual patch against a throwaway Express application. Connect/provision the project first, deliberately add the known-vulnerable package, then run:
+
+```bash
+npm install --save-exact node-serialize@0.0.4
+npx @patchstack/connect demo node-serialize
+```
+
+The demo command does not install the vulnerable package. It verifies the exact version in the lockfile, posts the production npm manifest to the configured site, polls the corresponding Pulse rules endpoint for rule `18843`, runs the normal `protect` installer, checks that the guard is wired, and prints one exploit request plus one benign control request. It never starts or restarts the application and never sends either test request itself.
+
+For a read-only walkthrough that can be run before or during the demo, use:
+
+```bash
+npx @patchstack/connect demo-guide node-serialize
+```
+
+The guide inspects the Host-created site configuration and lockfile, explains that no deployment is required, shows the complete prepare → run → restart → prove → clean-up sequence, and ends with the next exact command for the project's current state. Pass the same `--url` option when the test endpoint differs from the default.
+
+Use `--url http://localhost:PORT/api/tasks` when the app does not use the default `http://localhost:3000/api/tasks`. Remove the deliberately vulnerable dependency after the walkthrough.
+
 ## The disclosure widget
 
 The widget is a floating "Report a vulnerability" button — a disclosure channel for anyone who spots a bug on the site. The connector manages its install so the UUID never has to be copied by hand: