From 08d5644074140a02f37a34ab1de3f7735707e054 Mon Sep 17 00:00:00 2001
From: Dave Jong <dave.jong@patchstack.com>
Date: Wed, 15 Jul 2026 18:16:34 +0200
Subject: [PATCH 1/3] test(protect): typecheck scaffolded templates against the
 real API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Templates are excluded from connect's tsconfig (they import framework + JSON files that only exist
after scaffolding), so a template type bug ships silently — a broken install has slipped out this
way before. scripts/typecheck-templates.mjs assembles each template in a scratch dir with the real
@patchstack/connect/protect declarations, a stub rules JSON, and loose framework-type shims, then
runs `tsc --noEmit`. Chained into `npm run typecheck` so CI + prepublish cover it. Verified it fails
on the exact bug class it targets (a string-typed `mode`) and passes on all 6 current templates.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .gitignore                      |  3 ++
 package.json                    |  3 +-
 scripts/typecheck-templates.mjs | 90 +++++++++++++++++++++++++++++++++
 3 files changed, 95 insertions(+), 1 deletion(-)
 create mode 100644 scripts/typecheck-templates.mjs

diff --git a/.gitignore b/.gitignore
index c53e637..a5f4cfa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,3 +17,6 @@ field-test/results/
 
 # test-build throwaway fixture (recreated on every run)
 test-build/.work/
+
+# template typecheck scratch dir
+.template-typecheck/
diff --git a/package.json b/package.json
index bceaaab..74687ca 100644
--- a/package.json
+++ b/package.json
@@ -43,7 +43,8 @@
     "test": "vitest run",
     "test:manifest": "bun scripts/test-manifest.ts",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && node scripts/typecheck-templates.mjs",
+    "typecheck:templates": "node scripts/typecheck-templates.mjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
diff --git a/scripts/typecheck-templates.mjs b/scripts/typecheck-templates.mjs
new file mode 100644
index 0000000..3a5d553
--- /dev/null
+++ b/scripts/typecheck-templates.mjs
@@ -0,0 +1,90 @@
+// Typecheck the scaffolded `src/protect/templates/*.ts` the way a target app's `tsc` would.
+//
+// WHY: templates are deliberately excluded from connect's own tsconfig (they import framework +
+// JSON files that only exist AFTER scaffolding), so a template type bug ships silently — a broken
+// install has slipped out this way before (a `string`-typed `mode`, a non-generic `screenResponse`
+// return that a strict app's tsc then rejected). This assembles each template in a scratch dir with
+// the pieces it expects — the REAL `@patchstack/connect/protect` declarations, a stub rules JSON,
+// and loose shims for the framework type-only imports — then runs `tsc --noEmit`. It catches
+// template-vs-protect-API drift (that class of bug). Framework types are shimmed, not installed, so
+// it does NOT verify a handler matches its framework's exact hook signature — a possible follow-up.
+
+import { mkdirSync, rmSync, copyFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const ROOT = process.cwd();
+const TEMPLATES = join(ROOT, 'src/protect/templates');
+const OUT = join(ROOT, '.template-typecheck');
+
+rmSync(OUT, { recursive: true, force: true });
+mkdirSync(OUT, { recursive: true });
+
+// Copy every .ts template into the scratch dir.
+const templates = readdirSync(TEMPLATES).filter((f) => f.endsWith('.ts'));
+for (const f of templates) copyFileSync(join(TEMPLATES, f), join(OUT, f));
+
+// The JSON the templates import: the real starter rules (register-into-app templates import
+// ./rules.json) + a stub for the seam templates' co-located ./patchstack.rules.json.
+copyFileSync(join(TEMPLATES, 'rules.json'), join(OUT, 'rules.json'));
+writeFileSync(join(OUT, 'patchstack.rules.json'), '[]\n');
+
+// The real hand-authored declarations for @patchstack/connect/protect — this is what we check against.
+copyFileSync(join(ROOT, 'src/protect/protect.d.ts'), join(OUT, 'protect-types.d.ts'));
+
+// Loose shims for the framework type-only imports (we don't install the frameworks). Signatures
+// mirror the real hooks closely enough to catch obvious wiring mistakes without full fidelity.
+writeFileSync(
+  join(OUT, 'shims.d.ts'),
+  `declare module "astro" {
+  export type MiddlewareHandler = (
+    context: { request: Request },
+    next: () => Promise<Response>,
+  ) => Promise<Response> | Response;
+}
+declare module "@sveltejs/kit" {
+  export type Handle = (input: {
+    event: { request: Request };
+    resolve: (event: unknown) => Promise<Response>;
+  }) => Promise<Response> | Response;
+}
+`,
+);
+
+writeFileSync(
+  join(OUT, 'tsconfig.json'),
+  JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ES2022',
+        module: 'ESNext',
+        moduleResolution: 'Bundler',
+        lib: ['ES2022', 'DOM'],
+        types: ['node'],
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        resolveJsonModule: true,
+        isolatedModules: true,
+        noEmit: true,
+        baseUrl: '.',
+        paths: { '@patchstack/connect/protect': ['./protect-types'] },
+      },
+      include: ['*.ts'],
+    },
+    null,
+    2,
+  ),
+);
+
+const tsc = join(ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'tsc.cmd' : 'tsc');
+try {
+  execFileSync(tsc, ['--noEmit', '-p', join(OUT, 'tsconfig.json')], { stdio: 'inherit' });
+  console.log(`template typecheck: OK (${templates.length} templates)`);
+  rmSync(OUT, { recursive: true, force: true });
+} catch {
+  console.error(`\ntemplate typecheck FAILED — a scaffolded template would not compile in a user's app.`);
+  console.error(`(scratch dir left at ${OUT} for inspection)`);
+  process.exit(1);
+}

From ca2692821982f27e0c64c3aef0bfab884ec62b55 Mon Sep 17 00:00:00 2001
From: Dave Jong <dave.jong@patchstack.com>
Date: Wed, 15 Jul 2026 18:27:34 +0200
Subject: [PATCH 2/3] feat(protect): NestJS adapter + shared register-into-app
 helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

NestJS on the default Express platform accepts `app.use(...)` middleware in the bootstrap, so the
guard wires the same way Express/Fastify do — no Nest module/decorators needed. Anchored on
`NestFactory.create(...)`, reusing the framework-agnostic guard.

Extracted the register-into-app pattern (three adapters now share it) into install/register.ts
(wireRegister/verifyRegister + RegisterSpec) and the app-instance finder into install/find-app.ts;
Express + Fastify are now thin specs on top. hasDependency() moved to util.ts. No behavior change
for the existing adapters (their tests are unchanged and green).

Registered most-specific-first (… → astro → nestjs → fastify → express → generic). AGENT-INSTALL
lists NestJS. +2 tests, 458 total, typecheck (incl. template check) + build clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENT-INSTALL.md                        |   2 +-
 src/protect/install/adapters/express.ts | 139 +++---------------------
 src/protect/install/adapters/fastify.ts | 137 +++--------------------
 src/protect/install/adapters/nestjs.ts  |  25 +++++
 src/protect/install/find-app.ts         |  51 +++++++++
 src/protect/install/index.ts            |   2 +
 src/protect/install/register.ts         |  66 +++++++++++
 src/protect/install/util.ts             |  10 ++
 tests/protect/adapters.test.ts          |  41 +++++++
 9 files changed, 228 insertions(+), 245 deletions(-)
 create mode 100644 src/protect/install/adapters/nestjs.ts
 create mode 100644 src/protect/install/find-app.ts
 create mode 100644 src/protect/install/register.ts

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index 3a59db9..c48d595 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; 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`), **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).
+- 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).
 - 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/protect/install/adapters/express.ts b/src/protect/install/adapters/express.ts
index dade25b..c21c1ac 100644
--- a/src/protect/install/adapters/express.ts
+++ b/src/protect/install/adapters/express.ts
@@ -1,130 +1,23 @@
 // Adapter: Express (Node). Scaffolds the framework-agnostic guard and wires it as the first
 // middleware — `app.use(patchstackMiddleware)` right after the `express()` app is created.
-// Dependency-free anchor + #region-marker patching (same approach as the tanstack adapter).
-
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname, relative } from 'node:path';
-import { read, log } from '../util.js';
-import { scaffoldGeneric } from '../generic.js';
-import type { Adapter, WireOptions, WireResult, VerifyResult } from '../types.js';
-
-const APP_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*express\(\)/;
-const REGION = '// #region patchstack (managed by patchstack-connect protect — do not edit)';
-
-function hasExpressDep(cwd: string): boolean {
-  try {
-    const pkg = JSON.parse(read(join(cwd, 'package.json')));
-    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }.express);
-  } catch {
-    return false;
-  }
-}
-
-// Find the source file + variable where the Express app is created (`const app = express()`).
-function findExpressApp(cwd: string): { relPath: string; appVar: string } | null {
-  const root = existsSync(join(cwd, 'src')) ? join(cwd, 'src') : cwd;
-  let hit: { relPath: string; appVar: string } | null = null;
-  const walk = (dir: string): void => {
-    if (hit) return;
-    let entries: string[];
-    try {
-      entries = readdirSync(dir);
-    } catch {
-      return;
-    }
-    for (const name of entries) {
-      if (hit) return;
-      if (name === 'node_modules' || name === 'patchstack' || name.startsWith('.')) continue;
-      const p = join(dir, name);
-      let st;
-      try {
-        st = statSync(p);
-      } catch {
-        continue;
-      }
-      if (st.isDirectory()) walk(p);
-      else if (/\.(?:ts|js|mjs|cjs)$/.test(name)) {
-        let src: string;
-        try {
-          src = readFileSync(p, 'utf8');
-        } catch {
-          continue;
-        }
-        const m = APP_RE.exec(src);
-        if (m) hit = { relPath: relative(cwd, p).replace(/\\/g, '/'), appVar: m[1]! };
-      }
-    }
-  };
-  walk(root);
-  return hit;
-}
-
-function detect(cwd: string): boolean {
-  return hasExpressDep(cwd) && findExpressApp(cwd) !== null;
-}
-
-function importSpecifier(fromRel: string, toRel: string): string {
-  let spec = relative(dirname(fromRel), toRel).replace(/\\/g, '/').replace(/\.(?:ts|js)$/, '');
-  if (!spec.startsWith('.')) spec = `./${spec}`;
-  return spec;
-}
-
-function wire(cwd: string, opts: WireOptions): WireResult {
-  const { changed, dir } = scaffoldGeneric(cwd, opts);
-  const entry = findExpressApp(cwd);
-  if (!entry) {
-    log('express detected but no `= express()` site found — scaffolded guard; add app.use(patchstackMiddleware) yourself');
-    return { ok: true, changed };
-  }
-
-  const p = join(cwd, entry.relPath);
-  let s = read(p);
-  if (s.includes('patchstackMiddleware')) {
-    log(`express entry ${entry.relPath} already wired`);
-    return { ok: true, changed };
-  }
-
-  const spec = importSpecifier(entry.relPath, `${dir}/guard`);
-  const importLine = `import { patchstackMiddleware } from "${spec}";`;
-  // add the import after the last existing import (else at top)
-  const lines = s.split('\n');
-  let lastImport = -1;
-  for (let i = 0; i < lines.length; i++) if (/^\s*import\b/.test(lines[i] ?? '')) lastImport = i;
-  lines.splice(lastImport + 1, 0, importLine);
-  // insert `app.use(patchstackMiddleware)` right after the express() app line
-  const appIdx = lines.findIndex((l) => APP_RE.test(l));
-  if (appIdx !== -1) {
-    lines.splice(appIdx + 1, 0, REGION, `${entry.appVar}.use(patchstackMiddleware);`, '// #endregion patchstack');
-  }
-  s = lines.join('\n');
-  writeFileSync(p, s);
-  changed.push(entry.relPath);
-  log(`patched ${entry.relPath} (${entry.appVar}.use(patchstackMiddleware))`);
-  return { ok: true, changed: [...new Set(changed)] };
-}
-
-function verify(cwd: string): VerifyResult {
-  const dir = existsSync(join(cwd, 'src')) ? 'src/patchstack' : 'patchstack';
-  const scaffolded = existsSync(join(cwd, dir, 'guard.ts'));
-  const entry = findExpressApp(cwd);
-  const wired = entry ? read(join(cwd, entry.relPath)).includes('patchstackMiddleware') : false;
-  return {
-    wired: scaffolded && wired,
-    checks: [
-      { label: 'generic guard scaffolded', ok: scaffolded, hint: 'run `patchstack-connect protect`' },
-      {
-        label: 'app.use(patchstackMiddleware) wired into the Express app',
-        ok: wired,
-        hint: 'add `app.use(patchstackMiddleware)` right after you create your express() app',
-      },
-    ],
-  };
-}
+import { hasDependency } from '../util.js';
+import { findAppInstance } from '../find-app.js';
+import { wireRegister, verifyRegister, type RegisterSpec } from '../register.js';
+import type { Adapter } from '../types.js';
+
+const SPEC: RegisterSpec = {
+  appRe: /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*express\(\)/,
+  guardTemplate: 'generic-guard.ts',
+  importName: 'patchstackMiddleware',
+  call: (v) => `${v}.use(patchstackMiddleware);`,
+  label: 'Express app',
+  manualHint: 'add `app.use(patchstackMiddleware)` right after you create your express() app',
+};
 
 export const expressAdapter: Adapter = {
   name: 'express',
   label: 'Express (Node)',
-  detect,
-  wire,
-  verify,
+  detect: (cwd) => hasDependency(cwd, 'express') && findAppInstance(cwd, SPEC.appRe) !== null,
+  wire: (cwd, opts) => wireRegister(cwd, opts, SPEC),
+  verify: (cwd) => verifyRegister(cwd, SPEC),
 };
diff --git a/src/protect/install/adapters/fastify.ts b/src/protect/install/adapters/fastify.ts
index 8b5fe4a..f9be8f8 100644
--- a/src/protect/install/adapters/fastify.ts
+++ b/src/protect/install/adapters/fastify.ts
@@ -1,128 +1,23 @@
 // Adapter: Fastify (Node). Scaffolds the Fastify guard plugin and registers it on the app —
 // `app.register(patchstackFastify)` right after the `fastify()` instance is created.
-// Dependency-free anchor + #region-marker patching (same approach as the express adapter).
-
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname, relative } from 'node:path';
-import { read, log } from '../util.js';
-import { scaffoldGeneric } from '../generic.js';
-import type { Adapter, WireOptions, WireResult, VerifyResult } from '../types.js';
-
-const APP_RE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:fastify|Fastify)\(/;
-const REGION = '// #region patchstack (managed by patchstack-connect protect — do not edit)';
-
-function hasFastifyDep(cwd: string): boolean {
-  try {
-    const pkg = JSON.parse(read(join(cwd, 'package.json')));
-    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }.fastify);
-  } catch {
-    return false;
-  }
-}
-
-// Find the source file + variable where the Fastify app is created (`const app = fastify()`).
-function findFastifyApp(cwd: string): { relPath: string; appVar: string } | null {
-  const root = existsSync(join(cwd, 'src')) ? join(cwd, 'src') : cwd;
-  let hit: { relPath: string; appVar: string } | null = null;
-  const walk = (dir: string): void => {
-    if (hit) return;
-    let entries: string[];
-    try {
-      entries = readdirSync(dir);
-    } catch {
-      return;
-    }
-    for (const name of entries) {
-      if (hit) return;
-      if (name === 'node_modules' || name === 'patchstack' || name.startsWith('.')) continue;
-      const p = join(dir, name);
-      let st;
-      try {
-        st = statSync(p);
-      } catch {
-        continue;
-      }
-      if (st.isDirectory()) walk(p);
-      else if (/\.(?:ts|js|mjs|cjs)$/.test(name)) {
-        let src: string;
-        try {
-          src = readFileSync(p, 'utf8');
-        } catch {
-          continue;
-        }
-        const m = APP_RE.exec(src);
-        if (m) hit = { relPath: relative(cwd, p).replace(/\\/g, '/'), appVar: m[1]! };
-      }
-    }
-  };
-  walk(root);
-  return hit;
-}
-
-function detect(cwd: string): boolean {
-  return hasFastifyDep(cwd) && findFastifyApp(cwd) !== null;
-}
-
-function importSpecifier(fromRel: string, toRel: string): string {
-  let spec = relative(dirname(fromRel), toRel).replace(/\\/g, '/').replace(/\.(?:ts|js)$/, '');
-  if (!spec.startsWith('.')) spec = `./${spec}`;
-  return spec;
-}
-
-function wire(cwd: string, opts: WireOptions): WireResult {
-  const { changed, dir } = scaffoldGeneric(cwd, opts, 'fastify-plugin.ts');
-  const entry = findFastifyApp(cwd);
-  if (!entry) {
-    log('fastify detected but no `= fastify()` site found — scaffolded plugin; register it yourself: app.register(patchstackFastify)');
-    return { ok: true, changed };
-  }
-
-  const p = join(cwd, entry.relPath);
-  let s = read(p);
-  if (s.includes('patchstackFastify')) {
-    log(`fastify entry ${entry.relPath} already wired`);
-    return { ok: true, changed };
-  }
-
-  const spec = importSpecifier(entry.relPath, `${dir}/guard`);
-  const importLine = `import { patchstackFastify } from "${spec}";`;
-  const lines = s.split('\n');
-  let lastImport = -1;
-  for (let i = 0; i < lines.length; i++) if (/^\s*import\b/.test(lines[i] ?? '')) lastImport = i;
-  lines.splice(lastImport + 1, 0, importLine);
-  const appIdx = lines.findIndex((l) => APP_RE.test(l));
-  if (appIdx !== -1) {
-    lines.splice(appIdx + 1, 0, REGION, `${entry.appVar}.register(patchstackFastify);`, '// #endregion patchstack');
-  }
-  s = lines.join('\n');
-  writeFileSync(p, s);
-  changed.push(entry.relPath);
-  log(`patched ${entry.relPath} (${entry.appVar}.register(patchstackFastify))`);
-  return { ok: true, changed: [...new Set(changed)] };
-}
-
-function verify(cwd: string): VerifyResult {
-  const dir = existsSync(join(cwd, 'src')) ? 'src/patchstack' : 'patchstack';
-  const scaffolded = existsSync(join(cwd, dir, 'guard.ts'));
-  const entry = findFastifyApp(cwd);
-  const wired = entry ? read(join(cwd, entry.relPath)).includes('patchstackFastify') : false;
-  return {
-    wired: scaffolded && wired,
-    checks: [
-      { label: 'Fastify guard plugin scaffolded', ok: scaffolded, hint: 'run `patchstack-connect protect`' },
-      {
-        label: 'app.register(patchstackFastify) wired into the Fastify app',
-        ok: wired,
-        hint: 'add `app.register(patchstackFastify)` right after you create your fastify() app',
-      },
-    ],
-  };
-}
+import { hasDependency } from '../util.js';
+import { findAppInstance } from '../find-app.js';
+import { wireRegister, verifyRegister, type RegisterSpec } from '../register.js';
+import type { Adapter } from '../types.js';
+
+const SPEC: RegisterSpec = {
+  appRe: /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:fastify|Fastify)\(/,
+  guardTemplate: 'fastify-plugin.ts',
+  importName: 'patchstackFastify',
+  call: (v) => `${v}.register(patchstackFastify);`,
+  label: 'Fastify app',
+  manualHint: 'add `app.register(patchstackFastify)` right after you create your fastify() app',
+};
 
 export const fastifyAdapter: Adapter = {
   name: 'fastify',
   label: 'Fastify (Node)',
-  detect,
-  wire,
-  verify,
+  detect: (cwd) => hasDependency(cwd, 'fastify') && findAppInstance(cwd, SPEC.appRe) !== null,
+  wire: (cwd, opts) => wireRegister(cwd, opts, SPEC),
+  verify: (cwd) => verifyRegister(cwd, SPEC),
 };
diff --git a/src/protect/install/adapters/nestjs.ts b/src/protect/install/adapters/nestjs.ts
new file mode 100644
index 0000000..bf198e2
--- /dev/null
+++ b/src/protect/install/adapters/nestjs.ts
@@ -0,0 +1,25 @@
+// Adapter: NestJS. Wires the guard in the bootstrap file — `app.use(patchstackMiddleware)` right
+// after `NestFactory.create(...)`. Nest's INestApplication.use() accepts Express-style middleware
+// (the default platform), so this reuses the framework-agnostic guard rather than a Nest module +
+// decorators. On the Fastify platform the guard is still fail-open; response screening isn't wired.
+import { hasDependency } from '../util.js';
+import { findAppInstance } from '../find-app.js';
+import { wireRegister, verifyRegister, type RegisterSpec } from '../register.js';
+import type { Adapter } from '../types.js';
+
+const SPEC: RegisterSpec = {
+  appRe: /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+NestFactory\.create/,
+  guardTemplate: 'generic-guard.ts',
+  importName: 'patchstackMiddleware',
+  call: (v) => `${v}.use(patchstackMiddleware);`,
+  label: 'NestJS app',
+  manualHint: 'add `app.use(patchstackMiddleware)` right after your NestFactory.create(...) call',
+};
+
+export const nestjsAdapter: Adapter = {
+  name: 'nestjs',
+  label: 'NestJS',
+  detect: (cwd) => hasDependency(cwd, '@nestjs/core') && findAppInstance(cwd, SPEC.appRe) !== null,
+  wire: (cwd, opts) => wireRegister(cwd, opts, SPEC),
+  verify: (cwd) => verifyRegister(cwd, SPEC),
+};
diff --git a/src/protect/install/find-app.ts b/src/protect/install/find-app.ts
new file mode 100644
index 0000000..ae0e8e1
--- /dev/null
+++ b/src/protect/install/find-app.ts
@@ -0,0 +1,51 @@
+// Locate the source file + variable where an app instance is created, for the register-into-app
+// adapters (Express/Fastify/NestJS). Dependency-free: walk src/ (or the repo root) for a source
+// file matching `re`, which MUST capture the app variable name in group 1.
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+
+export function findAppInstance(cwd: string, re: RegExp): { relPath: string; appVar: string } | null {
+  const root = existsSync(join(cwd, 'src')) ? join(cwd, 'src') : cwd;
+  let hit: { relPath: string; appVar: string } | null = null;
+  const walk = (dir: string): void => {
+    if (hit) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (hit) return;
+      if (name === 'node_modules' || name === 'patchstack' || name.startsWith('.')) continue;
+      const p = join(dir, name);
+      let st;
+      try {
+        st = statSync(p);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(p);
+      else if (/\.(?:ts|js|mjs|cjs)$/.test(name)) {
+        let src: string;
+        try {
+          src = readFileSync(p, 'utf8');
+        } catch {
+          continue;
+        }
+        const m = re.exec(src);
+        if (m) hit = { relPath: relative(cwd, p).replace(/\\/g, '/'), appVar: m[1]! };
+      }
+    }
+  };
+  walk(root);
+  return hit;
+}
+
+/** Relative ESM specifier from `fromRel` to `toRel` (both repo-relative, extension stripped). */
+export function importSpecifier(fromRel: string, toRel: string): string {
+  let spec = relative(dirname(fromRel), toRel).replace(/\\/g, '/').replace(/\.(?:ts|js)$/, '');
+  if (!spec.startsWith('.')) spec = `./${spec}`;
+  return spec;
+}
diff --git a/src/protect/install/index.ts b/src/protect/install/index.ts
index a8da0fd..4b42be2 100644
--- a/src/protect/install/index.ts
+++ b/src/protect/install/index.ts
@@ -11,6 +11,7 @@ import { tanstackSupabaseAdapter } from './adapters/tanstack-supabase.js';
 import { nextAdapter } from './adapters/next.js';
 import { sveltekitAdapter } from './adapters/sveltekit.js';
 import { astroAdapter } from './adapters/astro.js';
+import { nestjsAdapter } from './adapters/nestjs.js';
 import { fastifyAdapter } from './adapters/fastify.js';
 import { expressAdapter } from './adapters/express.js';
 import { scaffoldGeneric, wiringPlan, genericVerify } from './generic.js';
@@ -23,6 +24,7 @@ const ADAPTERS: Adapter[] = [
   nextAdapter,
   sveltekitAdapter,
   astroAdapter,
+  nestjsAdapter,
   fastifyAdapter,
   expressAdapter,
 ];
diff --git a/src/protect/install/register.ts b/src/protect/install/register.ts
new file mode 100644
index 0000000..9a9eb6b
--- /dev/null
+++ b/src/protect/install/register.ts
@@ -0,0 +1,66 @@
+// Shared "register-into-app" wiring for adapters whose framework exposes a mutable app instance you
+// hook a guard onto (Express `app.use`, Fastify `app.register`, NestJS `app.use` on main.ts). Scaffold
+// the guard, then insert the registration call right after the app instance is created — dependency-free
+// anchor + #region-marker patching, idempotent.
+
+import { writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { read, log } from './util.js';
+import { scaffoldGeneric } from './generic.js';
+import { findAppInstance, importSpecifier } from './find-app.js';
+import type { WireOptions, WireResult, VerifyResult } from './types.js';
+
+export interface RegisterSpec {
+  appRe: RegExp; // matches the app-instance line; MUST capture the app var in group 1
+  guardTemplate: string; // guard template scaffolded as src/patchstack/guard.ts
+  importName: string; // named export the entry imports from the guard
+  call: (appVar: string) => string; // the registration statement, e.g. `${v}.use(patchstackMiddleware);`
+  label: string; // human label for logs / verify checks, e.g. 'Express app'
+  manualHint: string; // guidance when no app-instance site is found
+}
+
+const REGION = '// #region patchstack (managed by patchstack-connect protect — do not edit)';
+
+export function wireRegister(cwd: string, opts: WireOptions, spec: RegisterSpec): WireResult {
+  const { changed, dir } = scaffoldGeneric(cwd, opts, spec.guardTemplate);
+  const entry = findAppInstance(cwd, spec.appRe);
+  if (!entry) {
+    log(`${spec.label} not located — scaffolded guard; ${spec.manualHint}`);
+    return { ok: true, changed };
+  }
+
+  const p = join(cwd, entry.relPath);
+  const s = read(p);
+  if (s.includes(spec.importName)) {
+    log(`${entry.relPath} already wired`);
+    return { ok: true, changed };
+  }
+
+  const importLine = `import { ${spec.importName} } from "${importSpecifier(entry.relPath, `${dir}/guard`)}";`;
+  const lines = s.split('\n');
+  let lastImport = -1;
+  for (let i = 0; i < lines.length; i++) if (/^\s*import\b/.test(lines[i] ?? '')) lastImport = i;
+  lines.splice(lastImport + 1, 0, importLine);
+  const appIdx = lines.findIndex((l) => spec.appRe.test(l));
+  if (appIdx !== -1) {
+    lines.splice(appIdx + 1, 0, REGION, spec.call(entry.appVar), '// #endregion patchstack');
+  }
+  writeFileSync(p, lines.join('\n'));
+  changed.push(entry.relPath);
+  log(`patched ${entry.relPath} (${spec.call(entry.appVar).trim()})`);
+  return { ok: true, changed: [...new Set(changed)] };
+}
+
+export function verifyRegister(cwd: string, spec: RegisterSpec): VerifyResult {
+  const dir = existsSync(join(cwd, 'src')) ? 'src/patchstack' : 'patchstack';
+  const scaffolded = existsSync(join(cwd, dir, 'guard.ts'));
+  const entry = findAppInstance(cwd, spec.appRe);
+  const wired = entry ? read(join(cwd, entry.relPath)).includes(spec.importName) : false;
+  return {
+    wired: scaffolded && wired,
+    checks: [
+      { label: `${spec.label} guard scaffolded`, ok: scaffolded, hint: 'run `patchstack-connect protect`' },
+      { label: `guard registered on the ${spec.label}`, ok: wired, hint: spec.manualHint },
+    ],
+  };
+}
diff --git a/src/protect/install/util.ts b/src/protect/install/util.ts
index 778914c..82121e7 100644
--- a/src/protect/install/util.ts
+++ b/src/protect/install/util.ts
@@ -7,6 +7,16 @@ import { fileURLToPath } from 'node:url';
 export const read = (p: string): string => readFileSync(p, 'utf8');
 export const log = (msg: string): void => console.log(`patchstack protect: ${msg}`);
 
+/** True when `name` is in the project's dependencies or devDependencies. */
+export function hasDependency(cwd: string, name: string): boolean {
+  try {
+    const pkg = JSON.parse(read(join(cwd, 'package.json')));
+    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }[name]);
+  } catch {
+    return false;
+  }
+}
+
 // Guard templates ship next to the built CLI (dist/protect/templates). Resolve for the built
 // layout (this code is bundled into dist/cli.js at the dist root → protect/templates) and the
 // source layout (this file lives in src/protect/install/ → ../templates).
diff --git a/tests/protect/adapters.test.ts b/tests/protect/adapters.test.ts
index 95cb717..6a3c7f8 100644
--- a/tests/protect/adapters.test.ts
+++ b/tests/protect/adapters.test.ts
@@ -171,3 +171,44 @@ describe('Fastify adapter', () => {
     }
   });
 });
+
+describe('NestJS adapter', () => {
+  function nestApp(): string {
+    const dir = tmp('ps-nest-');
+    writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'x', dependencies: { '@nestjs/core': '^10.0.0' } }));
+    mkdirSync(path.join(dir, 'src'), { recursive: true });
+    writeFileSync(
+      path.join(dir, 'src/main.ts'),
+      "import { NestFactory } from '@nestjs/core';\nimport { AppModule } from './app.module';\nasync function bootstrap() {\n  const app = await NestFactory.create(AppModule);\n  await app.listen(3000);\n}\nbootstrap();\n",
+    );
+    return dir;
+  }
+
+  it('scaffolds the guard and wires app.use(patchstackMiddleware) after NestFactory.create', () => {
+    const dir = nestApp();
+    try {
+      const res: any = runProtect(dir);
+      expect(res.status).toBe('wired');
+      expect(res.adapter).toBe('nestjs');
+      expect(existsSync(path.join(dir, 'src/patchstack/guard.ts'))).toBe(true);
+      const main = read(dir, 'src/main.ts');
+      expect(main).toContain('import { patchstackMiddleware } from "./patchstack/guard";');
+      expect(main).toContain('app.use(patchstackMiddleware);');
+      expect(main.indexOf('NestFactory.create')).toBeLessThan(main.indexOf('app.use(patchstackMiddleware)'));
+      expect(runVerify(dir).wired).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('is idempotent (re-run does not duplicate the middleware)', () => {
+    const dir = nestApp();
+    try {
+      runProtect(dir);
+      runProtect(dir);
+      expect(count(read(dir, 'src/main.ts'), 'app.use(patchstackMiddleware)')).toBe(1);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

From 4d6c20c14c1662db3829fed58106c167b3a6b8fb Mon Sep 17 00:00:00 2001
From: Dave Jong <dave.jong@patchstack.com>
Date: Wed, 15 Jul 2026 18:39:44 +0200
Subject: [PATCH 3/3] =?UTF-8?q?feat(protect):=20efficient=20rule=20sync=20?=
 =?UTF-8?q?=E2=80=94=20conditional=20fetch,=20jitter,=20pluggable=20cache?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Harden the per-site rule-delivery client:

- Conditional fetch: persist the response ETag alongside the cached bundle (envelope
  { bundle, etag }) and send If-None-Match on the next fetch; a 304 reuses the cached bundle with
  no re-download. Fully dormant until the rules API emits an ETag — with no ETag the client behaves
  exactly as before (a full fetch each refresh). Defensive against Responses without a headers
  object (some test mocks / non-standard fetch shims).
- Jitter: randomly shorten the effective cache TTL by up to 10% so many long-lived clients don't
  revalidate in lockstep. Downward-only, so "past TTL ⇒ refetch" still holds.
- Pluggable cache: new `ruleCache` option ({ read, write }, sync or async) for runtimes without a
  filesystem (Workers/Deno) to persist last-known-good in their own store; disk stays the default.
  The disk read accepts a legacy bare-bundle file for backward compatibility.

Applied to both the Pulse (siteUuid) and token clients; resolveRules threads the prior etag and
handles 304. +4 tests (rule-sync), 462 total, typecheck (incl. template check) + build clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/protect/engine/client.js       |  42 +++++++++---
 src/protect/engine/pulse-client.js |  40 ++++++++---
 src/protect/protect.d.ts           |  10 ++-
 src/protect/runtime.js             |  87 ++++++++++++++++++------
 tests/protect/rule-sync.test.ts    | 103 +++++++++++++++++++++++++++++
 5 files changed, 245 insertions(+), 37 deletions(-)
 create mode 100644 tests/protect/rule-sync.test.ts

diff --git a/src/protect/engine/client.js b/src/protect/engine/client.js
index 865b9f7..ab94bd0 100644
--- a/src/protect/engine/client.js
+++ b/src/protect/engine/client.js
@@ -1,17 +1,26 @@
 const DEFAULT_BASE_URL = 'https://api.patchstack.com';
 const DEFAULT_CACHE_TTL = 300_000;
+// Randomly shorten the effective TTL by up to this fraction so many long-lived clients don't all
+// revalidate on the same tick (spreads load against the rules API).
+const JITTER_FRACTION = 0.1;
 
+// Token-authenticated rules client. Conditional fetch (If-None-Match / 304) and the persisted
+// `etag` mirror PulseRuleClient; both are a no-op until the API emits an ETag and honors the
+// conditional request — with no ETag in the response the client behaves as before (full fetch).
 export class PatchstackRuleClient {
   #token;
   #baseUrl;
   #cacheTtl;
   #cache = null;
   #cacheTime = null;
+  #ttlEffective = 0;
+  #etag;
 
-  constructor({ token, baseUrl, cacheTtl } = {}) {
+  constructor({ token, baseUrl, cacheTtl, etag } = {}) {
     this.#token = token ?? process.env.PATCHSTACK_WAF_TOKEN;
     this.#baseUrl = baseUrl ?? process.env.PATCHSTACK_WAF_API_URL ?? DEFAULT_BASE_URL;
     this.#cacheTtl = cacheTtl ?? DEFAULT_CACHE_TTL;
+    this.#etag = etag ?? null;
 
     if (!this.#token) {
       throw new Error('Patchstack WAF token is required. Pass { token } or set PATCHSTACK_WAF_TOKEN env var.');
@@ -21,24 +30,32 @@ export class PatchstackRuleClient {
   async getRules() {
     const now = Date.now();
 
-    if (this.#cache && this.#cacheTime && (now - this.#cacheTime) < this.#cacheTtl) {
+    if (this.#cache && this.#cacheTime !== null && (now - this.#cacheTime) < this.#ttlEffective) {
       return this.#cache;
     }
 
     const url = `${this.#baseUrl}/api/get-rules/3`;
 
     try {
+      const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.#token}`,
+        'LicenseID': '1' // Hard-coded, is never actually used but needed by the API
+      };
+      if (this.#etag) headers['If-None-Match'] = this.#etag;
+
       const response = await fetch(url, {
         method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Authorization': `Bearer ${this.#token}`,
-          'LicenseID': '1' // Hard-coded, is never actually used but needed by the API
-        },
+        headers,
         body: JSON.stringify({}),
         signal: AbortSignal.timeout(30_000)
       });
 
+      if (response.status === 304) {
+        this.#touch(now); // revalidated — reset the clock (fresh jitter)
+        return this.#cache ?? { success: true, notModified: true, etag: this.#etag, firewall: [], whitelists: [], whitelist_keys: {} };
+      }
+
       if (!response.ok) {
         return {
           success: false,
@@ -53,13 +70,16 @@ export class PatchstackRuleClient {
 
       const result = {
         success: true,
+        notModified: false,
+        etag: response.headers?.get?.('etag') ?? null,
         firewall: Array.isArray(data.firewall) ? data.firewall : [],
         whitelists: Array.isArray(data.whitelists) ? data.whitelists : [],
         whitelist_keys: data.whitelist_keys ?? {}
       };
 
       this.#cache = result;
-      this.#cacheTime = now;
+      this.#etag = result.etag;
+      this.#touch(now);
 
       return result;
     } catch (err) {
@@ -75,8 +95,14 @@ export class PatchstackRuleClient {
     }
   }
 
+  #touch(now) {
+    this.#cacheTime = now;
+    this.#ttlEffective = this.#cacheTtl - Math.floor(Math.random() * this.#cacheTtl * JITTER_FRACTION);
+  }
+
   clearCache() {
     this.#cache = null;
     this.#cacheTime = null;
+    this.#etag = null;
   }
 }
diff --git a/src/protect/engine/pulse-client.js b/src/protect/engine/pulse-client.js
index 21e90a2..b285fe4 100644
--- a/src/protect/engine/pulse-client.js
+++ b/src/protect/engine/pulse-client.js
@@ -1,20 +1,32 @@
 const DEFAULT_BASE_URL = 'https://api.patchstack.com/monitor/pulse';
 const DEFAULT_CACHE_TTL = 300_000;
+// Randomly shorten the effective TTL by up to this fraction so many long-lived clients don't all
+// revalidate on the same tick (spreads load / avoids a thundering herd against the rules API).
+const JITTER_FRACTION = 0.1;
 
 // Per-site rules client for Pulse (npm/JS) apps. Public endpoint — the site UUID is the only
 // credential, passed in the path. Fail-open: any error returns success:false + empty rules so
 // createProtection falls back to the disk cache or the bundled rules.
+//
+// Conditional fetch: pass a prior `etag` (persisted with the last cached bundle) and the client
+// sends `If-None-Match`; a 304 returns `{ notModified: true }` so the caller reuses its cache
+// without re-downloading, and a 200 returns the new bundle plus its `etag` to persist. This is a
+// no-op until the rules API emits an ETag and honors If-None-Match — with no ETag in the response
+// the client simply behaves as before (a full fetch every refresh).
 export class PulseRuleClient {
   #siteUuid;
   #baseUrl;
   #cacheTtl;
   #cache = null;
   #cacheTime = null;
+  #ttlEffective = 0;
+  #etag;
 
-  constructor({ siteUuid, baseUrl, cacheTtl } = {}) {
+  constructor({ siteUuid, baseUrl, cacheTtl, etag } = {}) {
     this.#siteUuid = siteUuid ?? process.env.PATCHSTACK_SITE_UUID;
     this.#baseUrl = baseUrl ?? process.env.PATCHSTACK_PULSE_RULES_URL ?? DEFAULT_BASE_URL;
     this.#cacheTtl = cacheTtl ?? DEFAULT_CACHE_TTL;
+    this.#etag = etag ?? null;
     if (!this.#siteUuid) {
       throw new Error('Patchstack site UUID is required. Pass { siteUuid } or set PATCHSTACK_SITE_UUID.');
     }
@@ -22,28 +34,34 @@ export class PulseRuleClient {
 
   async getRules() {
     const now = Date.now();
-    if (this.#cache && this.#cacheTime && now - this.#cacheTime < this.#cacheTtl) {
+    if (this.#cache && this.#cacheTime !== null && now - this.#cacheTime < this.#ttlEffective) {
       return this.#cache;
     }
     const url = `${this.#baseUrl}/rules/${encodeURIComponent(this.#siteUuid)}`;
     try {
-      const response = await fetch(url, {
-        method: 'GET',
-        headers: { Accept: 'application/json' },
-        signal: AbortSignal.timeout(30_000),
-      });
+      const headers = { Accept: 'application/json' };
+      if (this.#etag) headers['If-None-Match'] = this.#etag;
+      const response = await fetch(url, { method: 'GET', headers, signal: AbortSignal.timeout(30_000) });
+
+      if (response.status === 304) {
+        this.#touch(now); // revalidated — reset the clock (fresh jitter)
+        return this.#cache ?? { success: true, notModified: true, etag: this.#etag, firewall: [], whitelists: [], whitelist_keys: {} };
+      }
       if (!response.ok) {
         return { success: false, error: `API returned ${response.status}`, firewall: [], whitelists: [], whitelist_keys: {} };
       }
       const data = await response.json();
       const result = {
         success: true,
+        notModified: false,
+        etag: response.headers?.get?.('etag') ?? null,
         firewall: Array.isArray(data.firewall) ? data.firewall : [],
         whitelists: Array.isArray(data.whitelists) ? data.whitelists : [],
         whitelist_keys: data.whitelist_keys ?? {},
       };
       this.#cache = result;
-      this.#cacheTime = now;
+      this.#etag = result.etag;
+      this.#touch(now);
       return result;
     } catch (err) {
       return {
@@ -54,8 +72,14 @@ export class PulseRuleClient {
     }
   }
 
+  #touch(now) {
+    this.#cacheTime = now;
+    this.#ttlEffective = this.#cacheTtl - Math.floor(Math.random() * this.#cacheTtl * JITTER_FRACTION);
+  }
+
   clearCache() {
     this.#cache = null;
     this.#cacheTime = null;
+    this.#etag = null;
   }
 }
diff --git a/src/protect/protect.d.ts b/src/protect/protect.d.ts
index 7426d6a..35e5530 100644
--- a/src/protect/protect.d.ts
+++ b/src/protect/protect.d.ts
@@ -37,8 +37,16 @@ export interface CreateProtectionOptions {
   siteUuid?: string;
   /** Override the Pulse rules API base URL. */
   pulseRulesUrl?: string;
-  /** Directory for the last-known-good rule cache. */
+  /** Directory for the last-known-good rule cache (disk — the default cache backend). */
   cacheDir?: string;
+  /**
+   * Pluggable last-known-good cache, for runtimes without a filesystem (Workers/Deno). Overrides
+   * the disk cache. Stores/returns an opaque envelope; read may return null when nothing is cached.
+   */
+  ruleCache?: {
+    read(): unknown | Promise<unknown>;
+    write(envelope: unknown): unknown | Promise<unknown>;
+  };
   /** Override the default response-phase (secret-leak) rule set. */
   responseRules?: unknown[];
   /** Override the default egress-phase (SSRF) rule set. */
diff --git a/src/protect/runtime.js b/src/protect/runtime.js
index 6aed194..25b665a 100644
--- a/src/protect/runtime.js
+++ b/src/protect/runtime.js
@@ -464,41 +464,45 @@ function leakResponse() {
 // --- rule source --------------------------------------------------------
 
 async function resolveRules(options) {
+  const cache = makeCache(options);
+
   if (options.siteUuid) {
-    const client = new PulseRuleClient({ siteUuid: options.siteUuid, baseUrl: options.pulseRulesUrl });
+    const prior = await cache.read(); // { bundle, etag } | null
+    const client = new PulseRuleClient({ siteUuid: options.siteUuid, baseUrl: options.pulseRulesUrl, etag: prior?.etag });
     const res = await client.getRules();
-    if (res.success) {
+    if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle);
+    if (res.success && !res.notModified) {
       const bundle = normalizeBundle(res);
-      cacheWrite(options.cacheDir, bundle);
+      await cache.write({ bundle, etag: res.etag ?? null });
       return bundle;
     }
-    const cached = cacheRead(options.cacheDir);
-    if (cached) {
-      options.onError?.(new Error(`pulse rule fetch failed (${res.error}); using cached bundle`));
-      return normalizeBundle(cached);
+    if (prior?.bundle) {
+      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? 'no usable response'}); using cached bundle`));
+      return normalizeBundle(prior.bundle);
     }
     if (options.rules) {
-      options.onError?.(new Error(`pulse rule fetch failed (${res.error}); using bundled fallback`));
+      options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? 'no usable response'}); using bundled fallback`));
       return normalizeBundle(options.rules);
     }
-    options.onError?.(new Error(`pulse rule fetch failed (${res.error}); no cache — running with no rules`));
+    options.onError?.(new Error(`pulse rule fetch failed (${res.error ?? 'no usable response'}); no cache — running with no rules`));
     return emptyBundle();
   }
 
   if (options.token) {
-    const client = new PatchstackRuleClient({ token: options.token, baseUrl: options.baseUrl });
+    const prior = await cache.read();
+    const client = new PatchstackRuleClient({ token: options.token, baseUrl: options.baseUrl, etag: prior?.etag });
     const res = await client.getRules();
-    if (res.success) {
+    if (res.success && res.notModified && prior?.bundle) return normalizeBundle(prior.bundle);
+    if (res.success && !res.notModified) {
       const bundle = normalizeBundle(res);
-      cacheWrite(options.cacheDir, bundle);
+      await cache.write({ bundle, etag: res.etag ?? null });
       return bundle;
     }
-    const cached = cacheRead(options.cacheDir);
-    if (cached) {
-      options.onError?.(new Error(`rule fetch failed (${res.error}); using cached bundle`));
-      return normalizeBundle(cached);
+    if (prior?.bundle) {
+      options.onError?.(new Error(`rule fetch failed (${res.error ?? 'no usable response'}); using cached bundle`));
+      return normalizeBundle(prior.bundle);
     }
-    options.onError?.(new Error(`rule fetch failed (${res.error}); no cache — running with no rules`));
+    options.onError?.(new Error(`rule fetch failed (${res.error ?? 'no usable response'}); no cache — running with no rules`));
     return emptyBundle();
   }
 
@@ -521,15 +525,46 @@ function emptyBundle() {
   return { firewall: [], whitelists: [], whitelist_keys: {} };
 }
 
+// The cache stores an envelope { bundle, etag } so a restart can revalidate with If-None-Match. A
+// pluggable adapter (options.ruleCache) lets runtimes without a filesystem (Workers/Deno) persist
+// last-known-good in their own store; the default is a disk cache under options.cacheDir. Both
+// paths are best-effort — a read/write error yields no cache rather than throwing.
+function makeCache(options) {
+  const adapter = options.ruleCache;
+  if (adapter && typeof adapter.read === 'function' && typeof adapter.write === 'function') {
+    return {
+      read: async () => {
+        try {
+          return toEnvelope(await adapter.read());
+        } catch {
+          return null;
+        }
+      },
+      write: async (env) => {
+        try {
+          await adapter.write(env);
+        } catch {
+          /* best-effort */
+        }
+      },
+    };
+  }
+  const dir = options.cacheDir;
+  return {
+    read: async () => cacheRead(dir),
+    write: async (env) => cacheWrite(dir, env),
+  };
+}
+
 function cachePath(dir) {
   return join(dir, 'patchstack-rules.json');
 }
 
-function cacheWrite(dir, bundle) {
+function cacheWrite(dir, env) {
   if (!dir) return;
   try {
     mkdirSync(dir, { recursive: true });
-    writeFileSync(cachePath(dir), JSON.stringify(bundle));
+    writeFileSync(cachePath(dir), JSON.stringify(env));
   } catch {
     /* cache is best-effort */
   }
@@ -538,12 +573,24 @@ function cacheWrite(dir, bundle) {
 function cacheRead(dir) {
   if (!dir) return null;
   try {
-    return JSON.parse(readFileSync(cachePath(dir), 'utf8'));
+    return toEnvelope(JSON.parse(readFileSync(cachePath(dir), 'utf8')));
   } catch {
     return null;
   }
 }
 
+// Accept the current { bundle, etag } envelope and a legacy bare bundle (pre-envelope cache files).
+function toEnvelope(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.bundle && typeof value.bundle === 'object') {
+    return { bundle: value.bundle, etag: value.etag ?? null };
+  }
+  if (Array.isArray(value.firewall) || Array.isArray(value.whitelists)) {
+    return { bundle: value, etag: null }; // legacy bare-bundle cache file
+  }
+  return null;
+}
+
 // --- responses ----------------------------------------------------------
 
 // Client-facing block text — deliberately generic: no WAF narrative, no rule title. The reason
diff --git a/tests/protect/rule-sync.test.ts b/tests/protect/rule-sync.test.ts
new file mode 100644
index 0000000..c408485
--- /dev/null
+++ b/tests/protect/rule-sync.test.ts
@@ -0,0 +1,103 @@
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createProtection, createServerFnGuard } from '../../src/protect/runtime.js';
+import { PulseRuleClient } from '../../src/protect/engine/pulse-client.js';
+
+const RULES = {
+  firewall: [{ id: 'rm-npm-0001', rule_v2: [{ parameter: 'post.title', match: { type: 'inline_xss' } }] }],
+  whitelists: [],
+  whitelist_keys: {},
+};
+const XSS = { title: '<img src=x onerror="steal()">' };
+const URL_OPT = 'https://x.test/monitor/pulse';
+const blocks = async (p: any) => (await createServerFnGuard({ protection: p })(XSS))?.rule;
+const ifNoneMatch = (init: any) => init?.headers?.['If-None-Match'] ?? null;
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('rule sync — conditional fetch (ETag / 304)', () => {
+  it('persists the etag, revalidates with If-None-Match, and reuses the cached bundle on 304', async () => {
+    const cacheDir = mkdtempSync(join(tmpdir(), 'ps-etag-'));
+    const sent: (string | null)[] = [];
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (_url: string, init: any) => {
+        sent.push(ifNoneMatch(init));
+        if (ifNoneMatch(init) === 'v1') return new Response(null, { status: 304 });
+        return new Response(JSON.stringify(RULES), { status: 200, headers: { etag: 'v1' } });
+      }),
+    );
+    try {
+      const p1 = await createProtection({ siteUuid: 's', pulseRulesUrl: URL_OPT, cacheDir, mode: 'block' });
+      expect(await blocks(p1)).toBe('rm-npm-0001');
+
+      const env = JSON.parse(readFileSync(join(cacheDir, 'patchstack-rules.json'), 'utf8'));
+      expect(env.etag).toBe('v1'); // etag persisted alongside the bundle
+      expect(env.bundle.firewall[0].id).toBe('rm-npm-0001');
+
+      const p2 = await createProtection({ siteUuid: 's', pulseRulesUrl: URL_OPT, cacheDir, mode: 'block' });
+      expect(await blocks(p2)).toBe('rm-npm-0001'); // still blocks — served from cache after a 304
+
+      expect(sent[0]).toBeNull(); // first fetch: no conditional header
+      expect(sent[1]).toBe('v1'); // second fetch: revalidated, no re-download
+    } finally {
+      rmSync(cacheDir, { recursive: true, force: true });
+    }
+  });
+
+  it('is dormant when the API returns no ETag — behaves like a plain full fetch each time', async () => {
+    const cacheDir = mkdtempSync(join(tmpdir(), 'ps-noetag-'));
+    const sent: (string | null)[] = [];
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (_url: string, init: any) => {
+        sent.push(ifNoneMatch(init));
+        return new Response(JSON.stringify(RULES), { status: 200 }); // no ETag header
+      }),
+    );
+    try {
+      await createProtection({ siteUuid: 's', pulseRulesUrl: URL_OPT, cacheDir, mode: 'block' });
+      await createProtection({ siteUuid: 's', pulseRulesUrl: URL_OPT, cacheDir, mode: 'block' });
+      expect(sent).toEqual([null, null]); // never sends If-None-Match (nothing to revalidate against)
+    } finally {
+      rmSync(cacheDir, { recursive: true, force: true });
+    }
+  });
+
+  it('PulseRuleClient sends If-None-Match when seeded and reports notModified on 304', async () => {
+    const fetchMock = vi.fn(async (_url: string, init: any) =>
+      ifNoneMatch(init) === 'abc' ? new Response(null, { status: 304 }) : new Response(JSON.stringify(RULES), { status: 200, headers: { etag: 'abc' } }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+    const res: any = await new PulseRuleClient({ siteUuid: 's', etag: 'abc' }).getRules();
+    expect((fetchMock.mock.calls[0]![1] as any).headers['If-None-Match']).toBe('abc');
+    expect(res.notModified).toBe(true);
+  });
+});
+
+describe('rule sync — pluggable cache', () => {
+  it('reads/writes a caller-supplied cache adapter instead of disk (last-known-good on failure)', async () => {
+    let stored: unknown = null;
+    const ruleCache = {
+      read: () => stored,
+      write: (env: unknown) => {
+        stored = env;
+      },
+    };
+
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify(RULES), { status: 200, headers: { etag: 'v9' } })));
+    const p1 = await createProtection({ siteUuid: 's', pulseRulesUrl: URL_OPT, ruleCache, mode: 'block' });
+    expect(await blocks(p1)).toBe('rm-npm-0001');
+    expect((stored as any).etag).toBe('v9'); // written to the adapter, not disk
+    expect((stored as any).bundle.firewall[0].id).toBe('rm-npm-0001');
+
+    // Fetch now fails and there is no bundled fallback — the adapter's last-known-good must block.
+    vi.stubGlobal('fetch', vi.fn(async () => {
+      throw new Error('down');
+    }));
+    const p2 = await createProtection({ siteUuid: 's', pulseRulesUrl: URL_OPT, ruleCache, mode: 'block' });
+    expect(await blocks(p2)).toBe('rm-npm-0001');
+  });
+});