From fb265c89d3450628ccdbad246b3f564261594eb2 Mon Sep 17 00:00:00 2001
From: Dave Jong <dave.jong@patchstack.com>
Date: Wed, 15 Jul 2026 09:41:43 +0200
Subject: [PATCH 1/2] feat(protect): opt-in route-level WAF (env) + `protect
 --demo` sample rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two scaffolder features (both build on the #75 guard.ts type-safety fix, included here):

Route-level WAF (env-gated, off by default):
- guard.ts exports guardRequest(request) — runs the request-phase rules via fetchGuard
  on a cloned request and returns a 403 on a match (fail-open).
- the scaffolded request middleware calls it only when PATCHSTACK_ROUTE_WAF=1, so a plain
  `GET /?file=../../etc/passwd` gets a 403. Opt-in because it runs broad request rules on
  all traffic (classic-WAF false-positive surface); the default only screens the data path.

`protect --demo`:
- seeds a broad, many-class sample rule set (src/protect/templates/demo-rules.json, generated
  from + kept in lockstep with examples/protect/demo-rules.json minus its _demo vectors) instead
  of the high-precision starter, and SKIPS baking a site UUID so the local sample rules stay
  active (a baked UUID makes the guard fetch live Pulse rules instead).
- default install now writes the starter rules only if absent (no longer clobbers a
  customized rules.json on re-run).
- disclosed in the CLI help + AGENT-INSTALL.md; PATCHSTACK_MODE / PATCHSTACK_ROUTE_WAF added
  to the env list.

Verified: real CLI `protect --demo` seeds the 11-class bundle; route-WAF blocks a path-traversal
URL (403) and allows benign; +8 scaffolder tests incl. a template/examples parity check. 416 tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENT-INSTALL.md                      |   2 +-
 src/cli.ts                            |  11 +-
 src/protect/install.ts                |  43 +++--
 src/protect/templates/demo-rules.json | 238 ++++++++++++++++++++++++++
 src/protect/templates/guard.ts        |  14 ++
 tests/protect/demo-rules.test.ts      |  10 ++
 tests/protect/install.test.ts         |  39 +++++
 7 files changed, 341 insertions(+), 16 deletions(-)
 create mode 100644 src/protect/templates/demo-rules.json

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index 472729a..2b556bf 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -8,7 +8,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 - It reads the project's **dependency list only** — from the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or, on bun projects (`bun.lock`/`bun.lockb`), by enumerating the installed packages under `node_modules/` — and sends package names + versions to Patchstack for vulnerability matching. No source code, no env var values, no file paths, no git history. (`mark-build` additionally stamps built HTML with a coarse stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL`, `CF_PAGES` — never their values.)
 - **`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, currently for TanStack Start + Supabase apps; its templates live under `dist/protect/`). It patches the app's Supabase client to route traffic through a same-origin guard — and it runs **only** when explicitly invoked; `scan`, `setup`, `guide`, `status`, and `mark-build` never invoke it.
+- The package also bundles an **opt-in** `protect` command (runtime exploit guard, currently for TanStack Start + Supabase apps; its templates live under `dist/protect/`). It patches the app's Supabase client to route traffic through a same-origin guard — and it runs **only** when explicitly invoked; `scan`, `setup`, `guide`, `status`, and `mark-build` never invoke it. Passing `--demo` seeds a broad sample rule set (for demonstrations, not production) instead of the default starter rules; it writes only local files.
 - 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
diff --git a/src/cli.ts b/src/cli.ts
index cb372a2..e90bfb6 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -43,9 +43,11 @@ Usage:
   patchstack-connect mark-build [options]            Stamp built HTML with a production flag +
                                                      build fingerprint, and ensure the widget
                                                      tag in built pages (run as a postbuild step)
-  patchstack-connect protect                         Install always-on runtime protection (the
+  patchstack-connect protect [--demo]                Install always-on runtime protection (the
                                                      guard) into a TanStack Start + Supabase app.
                                                      Covers the browser + server-function paths.
+                                                     --demo seeds a broad sample rule set (for
+                                                     demonstrations, not production).
   patchstack-connect guide [--full]                  Show this project's setup status (what's done,
                                                      what's missing, with tailored commands), then
                                                      print the full setup guide. --full prints the
@@ -66,6 +68,8 @@ Environment:
   PATCHSTACK_ENDPOINT     API endpoint (default: https://api.patchstack.com/monitor/pulse/manifest)
   PATCHSTACK_TIMEOUT_MS   Request timeout in ms (default: 30000)
   PATCHSTACK_ENVIRONMENT  Manifest environment: production | sandbox (default: production)
+  PATCHSTACK_MODE         (protect) Runtime guard mode: block (default) | dry-run
+  PATCHSTACK_ROUTE_WAF    (protect) Set to 1 to also screen every request at the route level (opt-in)
 
 Precedence: CLI flag > environment variable > .patchstackrc.json.
 
@@ -300,10 +304,11 @@ function reportSourceWidget(siteUuid: string): void {
   }
 }
 
-async function runProtectCommand(_args: ParsedArgs): Promise<number> {
+async function runProtectCommand(args: ParsedArgs): Promise<number> {
   // Best-effort: like mark-build, this runs during builds and must never fail one.
+  const demo = args.flags.get('demo') === true;
   try {
-    runProtect(process.cwd());
+    runProtect(process.cwd(), { demo });
   } catch (err) {
     console.warn(`patchstack protect: skipped (${(err as Error).message}).`);
   }
diff --git a/src/protect/install.ts b/src/protect/install.ts
index d15594a..5fa9651 100644
--- a/src/protect/install.ts
+++ b/src/protect/install.ts
@@ -19,9 +19,6 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES =
   [join(HERE, 'protect', 'templates'), join(HERE, 'templates')].find((p) => existsSync(p)) ??
   join(HERE, 'protect', 'templates');
-const APP = process.cwd();
-const PS_DIR = join(APP, 'src/integrations/patchstack');
-
 const read = (p: string) => readFileSync(p, 'utf8');
 const log = (msg: string) => console.log(`patchstack protect: ${msg}`);
 
@@ -41,7 +38,7 @@ const CLIENT_TUNNEL = [
 
 const START_IMPORTS = [
   'import { getRequest } from "@tanstack/react-start/server";',
-  'import { GUARD_PATH, handleGuardRequest, inspectServerFn, screenResponse } from "@/integrations/patchstack/guard";',
+  'import { GUARD_PATH, handleGuardRequest, inspectServerFn, screenResponse, guardRequest } from "@/integrations/patchstack/guard";',
 ].join('\n');
 
 const REQUEST_MIDDLEWARE_DEF = [
@@ -53,6 +50,12 @@ const REQUEST_MIDDLEWARE_DEF = [
   '  if (request) {',
   '    const { pathname } = new URL(request.url);',
   '    if (pathname === GUARD_PATH) return handleGuardRequest(request);',
+  '    // Optional route-level WAF: screen every request and 403 on a match. Opt-in via',
+  '    // PATCHSTACK_ROUTE_WAF=1 (runs the request rules on all traffic — classic-WAF FP surface).',
+  '    if (process.env.PATCHSTACK_ROUTE_WAF === "1") {',
+  '      const blocked = await guardRequest(request);',
+  '      if (blocked) return blocked;',
+  '    }',
   '  }',
   '  return screenResponse(await next());',
   '});',
@@ -83,12 +86,22 @@ export function detectSupportedStack(cwd: string): boolean {
   );
 }
 
-function scaffold(cwd: string): void {
+function scaffold(cwd: string, opts: { demo?: boolean } = {}): void {
   const dst = join(cwd, 'src/integrations/patchstack');
   mkdirSync(dst, { recursive: true });
-  copyFileSync(join(TEMPLATES, 'guard.ts'), join(dst, 'guard.ts'));
-  copyFileSync(join(TEMPLATES, 'rules.json'), join(dst, 'rules.json'));
-  log('scaffolded guard.ts + rules.json');
+  copyFileSync(join(TEMPLATES, 'guard.ts'), join(dst, 'guard.ts')); // guard.ts is managed — always refreshed
+  const rulesDst = join(dst, 'rules.json');
+  // Default: the high-precision starter, written only if absent (don't clobber the user's rules on
+  // re-run). --demo: (re)seed the broad multi-class sample bundle for a self-contained demonstration.
+  if (opts.demo) {
+    copyFileSync(join(TEMPLATES, 'demo-rules.json'), rulesDst);
+    log('scaffolded guard.ts + rules.json (demo sample rule set)');
+  } else if (!existsSync(rulesDst)) {
+    copyFileSync(join(TEMPLATES, 'rules.json'), rulesDst);
+    log('scaffolded guard.ts + rules.json (starter rules)');
+  } else {
+    log('scaffolded guard.ts (kept existing rules.json)');
+  }
 }
 
 // Bake the site UUID from .patchstackrc.json (written by `patchstack-connect scan`) into the
@@ -182,14 +195,20 @@ function patchStart(cwd: string): void {
 }
 
 /** Scaffold + wire the runtime guard into the app. */
-export function runProtect(cwd: string): void {
+export function runProtect(cwd: string, opts: { demo?: boolean } = {}): void {
   if (!detectSupportedStack(cwd)) {
     log('runtime protection currently supports TanStack Start + Supabase apps; stack not detected — skipping.');
     return;
   }
-  scaffold(cwd);
-  bakeSiteUuid(cwd);
+  scaffold(cwd, opts);
+  // In demo mode, keep the local sample rules active — don't bake a site UUID (which would make the
+  // guard fetch live Pulse rules instead of the bundled demo set).
+  if (!opts.demo) bakeSiteUuid(cwd);
   patchClient(cwd);
   patchStart(cwd);
-  log('done — guard wired and always-on (blocks by default). Set PATCHSTACK_MODE=dry-run for log-only.');
+  log(
+    opts.demo
+      ? 'done — guard wired with the demo sample rules (blocks by default). Set PATCHSTACK_MODE=dry-run for log-only.'
+      : 'done — guard wired and always-on (blocks by default). Set PATCHSTACK_MODE=dry-run for log-only.',
+  );
 }
diff --git a/src/protect/templates/demo-rules.json b/src/protect/templates/demo-rules.json
new file mode 100644
index 0000000..beaf232
--- /dev/null
+++ b/src/protect/templates/demo-rules.json
@@ -0,0 +1,238 @@
+{
+  "_comment": "DEMO sample rules scaffolded by `patchstack-connect protect --demo` — a broad, many-class set (SQLi/XSS/XXE/SSRF/PII/…) for demonstrations, NOT the production corpus. In production, rules come from the Patchstack API per site (via a baked site UUID / token). Kept in sync with examples/protect/demo-rules.json (minus its _demo test vectors).",
+  "firewall": [
+    {
+      "id": "demo-prototype-pollution",
+      "title": "Prototype pollution in request body",
+      "category": "prototype-pollution",
+      "rule_v2": [
+        {
+          "parameter": "raw",
+          "mutations": [
+            "urldecode"
+          ],
+          "match": {
+            "type": "contains",
+            "value": "__proto__"
+          }
+        },
+        {
+          "parameter": "rules",
+          "rules": [
+            {
+              "parameter": "raw",
+              "mutations": [
+                "urldecode"
+              ],
+              "match": {
+                "type": "contains",
+                "value": "constructor"
+              },
+              "inclusive": true
+            },
+            {
+              "parameter": "raw",
+              "mutations": [
+                "urldecode"
+              ],
+              "match": {
+                "type": "contains",
+                "value": "prototype"
+              },
+              "inclusive": true
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "demo-path-traversal",
+      "title": "Path traversal in a file/path parameter",
+      "category": "lfi",
+      "rule_v2": [
+        {
+          "parameter": [
+            "get.file",
+            "post.file",
+            "raw.file",
+            "get.path",
+            "post.path"
+          ],
+          "mutations": [
+            "urldecode"
+          ],
+          "match": {
+            "type": "contains",
+            "value": ".."
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-sqli",
+      "title": "SQL injection in a query parameter",
+      "category": "sqli",
+      "rule_v2": [
+        {
+          "parameter": [
+            "get.q",
+            "post.q",
+            "get.id",
+            "post.id",
+            "raw"
+          ],
+          "mutations": [
+            "urldecode"
+          ],
+          "match": {
+            "type": "regex",
+            "value": "/union\\s+select|;\\s*drop\\s+table|\\bor\\s+1\\s*=\\s*1\\b/i"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-xss",
+      "title": "Reflected/stored XSS in a text field",
+      "category": "xss",
+      "rule_v2": [
+        {
+          "parameter": [
+            "get.q",
+            "post.comment",
+            "post.title",
+            "raw"
+          ],
+          "mutations": [
+            "urldecode",
+            "htmlentitydecode"
+          ],
+          "match": {
+            "type": "regex",
+            "value": "/<script\\b|onerror\\s*=|javascript:/i"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-command-injection",
+      "title": "OS command injection in a host/cmd parameter",
+      "category": "command-injection",
+      "rule_v2": [
+        {
+          "parameter": [
+            "get.host",
+            "post.host",
+            "get.cmd",
+            "post.cmd"
+          ],
+          "mutations": [
+            "urldecode"
+          ],
+          "match": {
+            "type": "regex",
+            "value": "/[;&|`$()<>]/"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-nosql-injection",
+      "title": "NoSQL operator injection in request body",
+      "category": "nosqli",
+      "rule_v2": [
+        {
+          "parameter": "raw",
+          "match": {
+            "type": "regex",
+            "value": "/\"\\$(?:ne|gt|lt|gte|lte|where|regex|in|nin)\"\\s*:/i"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-xxe",
+      "title": "XML external entity (XXE) in request body",
+      "category": "xxe",
+      "rule_v2": [
+        {
+          "parameter": "raw",
+          "match": {
+            "type": "regex",
+            "value": "/<!ENTITY|<!DOCTYPE[^>]*SYSTEM/i"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-ssrf-request",
+      "title": "SSRF via a url parameter (request-side)",
+      "category": "ssrf",
+      "rule_v2": [
+        {
+          "parameter": [
+            "get.url",
+            "post.url",
+            "raw.url"
+          ],
+          "mutations": [
+            "urldecode"
+          ],
+          "match": {
+            "type": "regex",
+            "value": "/localhost|127\\.0\\.0\\.1|169\\.254\\.169\\.254|::1|metadata\\.google/i"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-resp-pii-email",
+      "title": "Email address leaking in response body",
+      "phase": "response",
+      "category": "pii-exposure",
+      "action": "redact",
+      "rule_v2": [
+        {
+          "parameter": "response.body",
+          "match": {
+            "type": "regex",
+            "value": "/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}/"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-resp-credit-card",
+      "title": "Credit-card number leaking in response body",
+      "phase": "response",
+      "category": "pii-exposure",
+      "action": "redact",
+      "rule_v2": [
+        {
+          "parameter": "response.body",
+          "match": {
+            "type": "regex",
+            "value": "/(?:\\d[ -]?){13,16}/"
+          }
+        }
+      ]
+    },
+    {
+      "id": "demo-egress-blocklist-host",
+      "title": "Outbound request to a known exfiltration host",
+      "phase": "egress",
+      "category": "exfiltration",
+      "rule_v2": [
+        {
+          "parameter": "egress.host",
+          "match": {
+            "type": "equals",
+            "value": "evil.example.com"
+          }
+        }
+      ]
+    }
+  ],
+  "whitelists": [],
+  "whitelist_keys": {}
+}
diff --git a/src/protect/templates/guard.ts b/src/protect/templates/guard.ts
index 0d2a770..1802735 100644
--- a/src/protect/templates/guard.ts
+++ b/src/protect/templates/guard.ts
@@ -89,3 +89,17 @@ export async function screenResponse<T>(response: T): Promise<T> {
     return response; // fail open
   }
 }
+
+// Optional route-level WAF: evaluate the request-phase rules on EVERY incoming request (not just
+// the Supabase tunnel / server functions) and return a 403 on a match. Off unless the app sets
+// PATCHSTACK_ROUTE_WAF=1 — enabling it runs the request rules on all traffic, which is a classic
+// WAF false-positive surface, so it is opt-in. `request.clone()` so the app can still read the body.
+let _reqGuard: ((request: Request) => Promise<Response | null>) | undefined;
+export async function guardRequest(request: Request): Promise<Response | null> {
+  try {
+    if (!_reqGuard) _reqGuard = (await getProtection()).fetchGuard();
+    return await _reqGuard(request.clone());
+  } catch {
+    return null; // fail open
+  }
+}
diff --git a/tests/protect/demo-rules.test.ts b/tests/protect/demo-rules.test.ts
index 938a87d..420fb2f 100644
--- a/tests/protect/demo-rules.test.ts
+++ b/tests/protect/demo-rules.test.ts
@@ -28,4 +28,14 @@ describe('demo rule set (examples/protect/demo-rules.json)', () => {
     expect(failures.map((f) => ({ id: f.id, exploitCaught: f.exploitCaught, benignOk: f.benignOk }))).toEqual([]);
     expect(results.length).toBe(withDemo.length);
   });
+
+  it('the scaffolded demo template (templates/demo-rules.json) matches this bundle, minus _demo', () => {
+    // `protect --demo` ships src/protect/templates/demo-rules.json; keep it in lockstep with this
+    // validated bundle so the scaffolded sample rules are exactly the ones proven above.
+    const tmpl = JSON.parse(
+      readFileSync(new URL('../../src/protect/templates/demo-rules.json', import.meta.url), 'utf8'),
+    );
+    const stripped = bundle.firewall.map(({ _demo, ...rule }: any) => rule);
+    expect(tmpl.firewall).toEqual(stripped);
+  });
 });
diff --git a/tests/protect/install.test.ts b/tests/protect/install.test.ts
index 196d554..ba7fbb7 100644
--- a/tests/protect/install.test.ts
+++ b/tests/protect/install.test.ts
@@ -86,6 +86,45 @@ describe('runProtect scaffolder', () => {
     expect(guard).toContain('export async function screenResponse<T>(response: T): Promise<T>');
   });
 
+  it('scaffolds the opt-in route-level WAF (gated on PATCHSTACK_ROUTE_WAF)', () => {
+    runProtect(dir);
+    const start = read(dir, 'src/start.ts');
+    const guard = read(dir, 'src/integrations/patchstack/guard.ts');
+    expect(start).toContain('process.env.PATCHSTACK_ROUTE_WAF === "1"');
+    expect(start).toContain('const blocked = await guardRequest(request);');
+    expect(guard).toContain('export async function guardRequest(');
+  });
+
+  it('--demo seeds the broad sample rule set and keeps it local (no baked site UUID)', () => {
+    writeFileSync(path.join(dir, '.patchstackrc.json'), JSON.stringify({ siteUuid: '123e4567-e89b-12d3-a456-426614174000' }));
+    runProtect(dir, { demo: true });
+    const ids = JSON.parse(read(dir, 'src/integrations/patchstack/rules.json')).firewall.map((r: any) => r.id);
+    expect(ids).toContain('demo-sqli'); // the broad sample bundle
+    expect(ids).toContain('demo-egress-blocklist-host');
+    // demo keeps the local rules active → the site UUID is NOT baked (else the guard fetches live rules)
+    const guard = read(dir, 'src/integrations/patchstack/guard.ts');
+    expect(guard).toContain('__PATCHSTACK_SITE_UUID__');
+    expect(guard).not.toContain('123e4567-e89b-12d3-a456-426614174000');
+  });
+
+  it('default install writes the starter rules and bakes a present site UUID', () => {
+    writeFileSync(path.join(dir, '.patchstackrc.json'), JSON.stringify({ siteUuid: '123e4567-e89b-12d3-a456-426614174000' }));
+    runProtect(dir);
+    const ids = JSON.parse(read(dir, 'src/integrations/patchstack/rules.json')).firewall.map((r: any) => r.id);
+    expect(ids.some((id: string) => id.startsWith('ps-fallback-'))).toBe(true);
+    const guard = read(dir, 'src/integrations/patchstack/guard.ts');
+    expect(guard).toContain('123e4567-e89b-12d3-a456-426614174000'); // baked → live Pulse rules
+    expect(guard).not.toContain('__PATCHSTACK_SITE_UUID__');
+  });
+
+  it('does not clobber an existing rules.json on a plain re-run', () => {
+    runProtect(dir);
+    const custom = JSON.stringify({ firewall: [{ id: 'my-custom-rule' }], whitelists: [], whitelist_keys: {} });
+    writeFileSync(path.join(dir, 'src/integrations/patchstack/rules.json'), custom);
+    runProtect(dir);
+    expect(JSON.parse(read(dir, 'src/integrations/patchstack/rules.json')).firewall[0].id).toBe('my-custom-rule');
+  });
+
   it('is idempotent — re-running does not duplicate wiring', () => {
     runProtect(dir);
     runProtect(dir);

From ca005de78815423573294c35f9e96b9e6f513426 Mon Sep 17 00:00:00 2001
From: Dave Jong <dave.jong@patchstack.com>
Date: Wed, 15 Jul 2026 09:56:56 +0200
Subject: [PATCH 2/2] feat(protect): reconcile start.ts guards in place
 (upgrade existing installs)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

patchStart previously skipped an already-wired start.ts, so a re-run after a
connect upgrade never refreshed the middleware (e.g. an existing app couldn't
pick up the new route-WAF hook). Make the generated blocks MANAGED:

- wrap each middleware block in `// #region patchstack-guard` … `// #endregion`
  markers; a re-run replaces the marked region in place (upgrade), and the guard
  import line is refreshed wholesale.
- migrate a legacy (pre-markers) block: bound it from its `const …` line (plus the
  comment header above) to its terminating `});`, and replace with the marked block.
- fresh installs insert as before. All paths stay idempotent (a second run is a no-op).

Verified end-to-end: re-running the CLI on a legacy-wired app adds the route-WAF
hook + markers + refreshed import with no duplication. +1 upgrade test (417 total).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/protect/install.ts        | 90 +++++++++++++++++++++--------------
 tests/protect/install.test.ts | 52 ++++++++++++++++++++
 2 files changed, 107 insertions(+), 35 deletions(-)

diff --git a/src/protect/install.ts b/src/protect/install.ts
index 5fa9651..6ac045d 100644
--- a/src/protect/install.ts
+++ b/src/protect/install.ts
@@ -36,22 +36,23 @@ const CLIENT_TUNNEL = [
   '',
 ].join('\n');
 
-const START_IMPORTS = [
-  'import { getRequest } from "@tanstack/react-start/server";',
-  'import { GUARD_PATH, handleGuardRequest, inspectServerFn, screenResponse, guardRequest } from "@/integrations/patchstack/guard";',
-].join('\n');
-
-const REQUEST_MIDDLEWARE_DEF = [
-  '',
-  '// Patchstack guard (browser tunnel): intercept tunneled Supabase traffic before anything else,',
-  '// then screen the outgoing response (SSR HTML / data) for leaked secrets & PII.',
+const GUARD_IMPORT =
+  'import { GUARD_PATH, handleGuardRequest, inspectServerFn, screenResponse, guardRequest } from "@/integrations/patchstack/guard";';
+const GUARD_IMPORT_RE = /import \{[^}]*\} from "@\/integrations\/patchstack\/guard";/;
+
+const START_IMPORTS = ['import { getRequest } from "@tanstack/react-start/server";', GUARD_IMPORT].join('\n');
+
+// Managed middleware blocks, delimited by #region markers so a re-run can UPGRADE them in place
+// (e.g. adding the route-WAF hook to an already-wired app) instead of skipping. Keep the markers —
+// reconcileBlock() keys off them.
+const REQUEST_MIDDLEWARE_BLOCK = [
+  '// #region patchstack-guard (managed by patchstack-connect protect — do not edit)',
+  '// Browser→Supabase tunnel + response screening; optional route WAF via PATCHSTACK_ROUTE_WAF=1.',
   'const patchstackGuard = createMiddleware().server(async ({ next }) => {',
   '  const request = getRequest();',
   '  if (request) {',
   '    const { pathname } = new URL(request.url);',
   '    if (pathname === GUARD_PATH) return handleGuardRequest(request);',
-  '    // Optional route-level WAF: screen every request and 403 on a match. Opt-in via',
-  '    // PATCHSTACK_ROUTE_WAF=1 (runs the request rules on all traffic — classic-WAF FP surface).',
   '    if (process.env.PATCHSTACK_ROUTE_WAF === "1") {',
   '      const blocked = await guardRequest(request);',
   '      if (blocked) return blocked;',
@@ -59,21 +60,49 @@ const REQUEST_MIDDLEWARE_DEF = [
   '  }',
   '  return screenResponse(await next());',
   '});',
-  '',
+  '// #endregion patchstack-guard',
 ].join('\n');
 
-const FUNCTION_MIDDLEWARE_DEF = [
-  '',
-  '// Patchstack guard (server functions): inspect server-fn args before they reach the database,',
-  '// covering apps that mutate via TanStack server functions (which bypass the browser tunnel).',
+const FUNCTION_MIDDLEWARE_BLOCK = [
+  '// #region patchstack-function-guard (managed by patchstack-connect protect — do not edit)',
+  '// Inspect server-function args before they reach the database.',
   'const patchstackFunctionGuard = createMiddleware({ type: "function" }).server(async ({ next, data }) => {',
   '  const blocked = await inspectServerFn(data);',
   '  if (blocked) throw new Error(blocked.message);',
   '  return next();',
   '});',
-  '',
+  '// #endregion patchstack-function-guard',
 ].join('\n');
 
+// Reconcile a managed block: replace a marked region in place (UPGRADE), migrate a legacy
+// (un-marked) block, or insert before `insertBefore` (fresh). Legacy blocks are our own single
+// arrow-fn statements whose only line-leading `});` is the terminator, so we bound them from the
+// `const` line (plus the comment header immediately above) to that `});`.
+function reconcileBlock(s: string, region: string, block: string, legacyConst: string, insertBefore: string): string {
+  const lines = s.split('\n');
+  const startMarker = `// #region ${region} `;
+  const endMarker = `// #endregion ${region}`;
+  const si = lines.findIndex((l) => l.includes(startMarker));
+  if (si !== -1) {
+    const ei = lines.findIndex((l, i) => i > si && l.trim() === endMarker);
+    if (ei !== -1) {
+      lines.splice(si, ei - si + 1, ...block.split('\n'));
+      return lines.join('\n');
+    }
+  }
+  const ci = lines.findIndex((l) => l.includes(legacyConst));
+  if (ci !== -1) {
+    const close = lines.findIndex((l, i) => i >= ci && l.trim() === '});');
+    if (close !== -1) {
+      let start = ci;
+      while (start > 0 && (lines[start - 1] ?? '').trim().startsWith('//')) start--; // eat old comment header
+      lines.splice(start, close - start + 1, ...block.split('\n'));
+      return lines.join('\n');
+    }
+  }
+  return s.replace(insertBefore, block + '\n\n' + insertBefore);
+}
+
 export function detectSupportedStack(cwd: string): boolean {
   const pkgPath = join(cwd, 'package.json');
   if (!existsSync(pkgPath)) return false;
@@ -150,29 +179,20 @@ function patchStart(cwd: string): void {
     return log('start.ts anchors not found — skipping (template changed?)');
   }
 
-  // Each step is independently idempotent, so re-running `protect` (including after a connect
-  // upgrade that adds a new guard) reconciles only what's missing — never duplicates, never
-  // silently skips a newly-added piece.
+  // Each step reconciles idempotently: a re-run (including after a connect upgrade) refreshes the
+  // managed blocks in place — never duplicates, never leaves a stale version behind.
   const original = s;
 
-  // Imports.
-  if (!s.includes('@/integrations/patchstack/guard')) {
+  // Imports — refresh the managed guard import line wholesale (upgrade), else insert both imports.
+  if (GUARD_IMPORT_RE.test(s)) {
+    s = s.replace(GUARD_IMPORT_RE, GUARD_IMPORT);
+  } else {
     s = s.replace(importAnchor, importAnchor + '\n' + START_IMPORTS);
-  } else if (!s.includes('inspectServerFn')) {
-    // Upgrade from a build that only wired the browser tunnel: pull in inspectServerFn.
-    s = s.replace(
-      'import { GUARD_PATH, handleGuardRequest } from "@/integrations/patchstack/guard";',
-      'import { GUARD_PATH, handleGuardRequest, inspectServerFn } from "@/integrations/patchstack/guard";',
-    );
   }
 
-  // Middleware definitions (each only if its const isn't already present).
-  if (!s.includes('const patchstackGuard =')) {
-    s = s.replace(exportAnchor, REQUEST_MIDDLEWARE_DEF + '\n' + exportAnchor);
-  }
-  if (!s.includes('const patchstackFunctionGuard =')) {
-    s = s.replace(exportAnchor, FUNCTION_MIDDLEWARE_DEF + '\n' + exportAnchor);
-  }
+  // Middleware blocks — upgrade a marked region / migrate a legacy block / insert fresh.
+  s = reconcileBlock(s, 'patchstack-guard', REQUEST_MIDDLEWARE_BLOCK, 'const patchstackGuard =', exportAnchor);
+  s = reconcileBlock(s, 'patchstack-function-guard', FUNCTION_MIDDLEWARE_BLOCK, 'const patchstackFunctionGuard =', exportAnchor);
 
   // Register the browser-tunnel guard in requestMiddleware.
   if (s.includes(rmAnchor) && !s.includes('requestMiddleware: [patchstackGuard')) {
diff --git a/tests/protect/install.test.ts b/tests/protect/install.test.ts
index ba7fbb7..05460c2 100644
--- a/tests/protect/install.test.ts
+++ b/tests/protect/install.test.ts
@@ -125,6 +125,58 @@ describe('runProtect scaffolder', () => {
     expect(JSON.parse(read(dir, 'src/integrations/patchstack/rules.json')).firewall[0].id).toBe('my-custom-rule');
   });
 
+  it('upgrades a legacy (pre-markers, no route-WAF) start.ts in place', () => {
+    // Simulate an app wired by an older published version: un-marked blocks, import lacking
+    // guardRequest, and no PATCHSTACK_ROUTE_WAF hook.
+    const legacy = `import { createStart, createMiddleware } from "@tanstack/react-start";
+import { getRequest } from "@tanstack/react-start/server";
+import { GUARD_PATH, handleGuardRequest, inspectServerFn, screenResponse } from "@/integrations/patchstack/guard";
+import { attachSupabaseAuth } from "@/integrations/supabase/auth-attacher";
+
+const errorMiddleware = createMiddleware().server(async ({ next }) => next());
+
+// Patchstack guard (browser tunnel): intercept tunneled Supabase traffic before anything else,
+// then screen the outgoing response (SSR HTML / data) for leaked secrets & PII.
+const patchstackGuard = createMiddleware().server(async ({ next }) => {
+  const request = getRequest();
+  if (request) {
+    const { pathname } = new URL(request.url);
+    if (pathname === GUARD_PATH) return handleGuardRequest(request);
+  }
+  return screenResponse(await next());
+});
+
+// Patchstack guard (server functions): inspect server-fn args before they reach the database.
+const patchstackFunctionGuard = createMiddleware({ type: "function" }).server(async ({ next, data }) => {
+  const blocked = await inspectServerFn(data);
+  if (blocked) throw new Error(blocked.message);
+  return next();
+});
+
+export const startInstance = createStart(() => ({
+  functionMiddleware: [patchstackFunctionGuard, attachSupabaseAuth],
+  requestMiddleware: [patchstackGuard, errorMiddleware],
+}));
+`;
+    writeFileSync(path.join(dir, 'src/start.ts'), legacy);
+    runProtect(dir);
+    const start = read(dir, 'src/start.ts');
+    // upgraded in place: route-WAF hook + guardRequest import now present, wrapped in markers
+    expect(start).toContain('// #region patchstack-guard ');
+    expect(start).toContain('process.env.PATCHSTACK_ROUTE_WAF === "1"');
+    expect(start).toContain('const blocked = await guardRequest(request);');
+    expect(start).toMatch(/import \{[^}]*guardRequest[^}]*\} from "@\/integrations\/patchstack\/guard";/);
+    // no duplication, old comment header gone, registrations intact
+    expect(count(start, 'const patchstackGuard =')).toBe(1);
+    expect(count(start, 'const patchstackFunctionGuard =')).toBe(1);
+    expect(start).not.toContain('intercept tunneled Supabase traffic before anything else');
+    expect(start).toContain('requestMiddleware: [patchstackGuard, errorMiddleware]');
+    // and a second run is a no-op
+    const twice = () => runProtect(dir);
+    twice();
+    expect(count(read(dir, 'src/start.ts'), 'const patchstackGuard =')).toBe(1);
+  });
+
   it('is idempotent — re-running does not duplicate wiring', () => {
     runProtect(dir);
     runProtect(dir);