From bb915b955ef792386822ecf2ed0c5d10bb0e4b52 Mon Sep 17 00:00:00 2001 From: Dave Jong Date: Tue, 17 Nov 2026 20:27:29 +0100 Subject: [PATCH] Extend real framework coverage and preserve streamed responses --- AGENT-INSTALL.md | 2 +- package.json | 1 + scripts/framework-consumers.mjs | 272 ++++++++++++++++++ src/protect/install/template-upgrade.ts | 26 +- src/protect/protect.d.ts | 3 + src/protect/runtime.js | 39 ++- src/protect/templates/fastify-plugin.cjs | 23 +- src/protect/templates/fastify-plugin.js | 23 +- src/protect/templates/fastify-plugin.ts | 23 +- src/protect/templates/nuxt-middleware.ts | 7 +- .../a-guard-without-its-fallback-file.test.ts | 2 +- 11 files changed, 374 insertions(+), 47 deletions(-) create mode 100644 scripts/framework-consumers.mjs diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md index 82c08d1f..1d63f001 100644 --- a/AGENT-INSTALL.md +++ b/AGENT-INSTALL.md @@ -117,7 +117,7 @@ Runtime rule polling also has a request-triggered check, for hosts that freeze i - The **widget tag** goes in the root HTML shell — the first of `index.html`, `public/index.html`, or `src/app.html` that exists — and only after a successful post, because it carries the site UUID. - The **production marker** goes in a root shell that is JSX rather than HTML (e.g. `src/routes/__root.tsx`, `app/layout.tsx`), inside a `{/* #region patchstack */}` block placed above the widget tag. It is written *before* the post: it carries no site UUID and needs no network, and build scripts commonly chain `patchstack-connect scan || true`, where waiting on the server would mean an offline build silently ships without the flag. The marker is guarded by the framework's own production expression (`import.meta.env.PROD`, or `process.env.NODE_ENV === 'production'`), so it is inert in dev and preview builds. Without it a server-rendered site has no built HTML for `mark-build` to stamp, and the widget treats the published site as build mode. `mark-build` writes to build output only (`dist/`, `build/`, `out/`, `.output/public/`, `_site/`), never to source. `guide` writes nothing, `init` writes only its own `.patchstackrc.json`, and `status` writes only the connected note in `.patchstackrc.json`. `guide` sends nothing either: it reports a site as connected from that note, which `scan`, `status` and `claim` keep current. - **`setup` runs `scan` → `protect` → map upload → live-rule lookup**, then reports the outcome. Provisioning precedes guard installation. The map is stamped into the guard source for the NEXT startup/build; restart an already-running preview/server to load it. The rule lookup uses the runtime validator and source-scoped local cache without creating a running guard or installing global hooks. Pending, ready-empty, and unknown generation states are distinguished; none proves the running app loaded the guard. Failed uploads/pulls appear under Missing and can be retried by rerunning setup. It also wires install scans, prebuild scans + map uploads, and postbuild marking (explicit build chains for Yarn, pnpm and Bun), preserving existing commands. It never starts, builds or deploys the app. In a Lovable or Replit project, or with explicit `--dev-sync`, recognizable single-command development scripts are wrapped for continuous synchronization; other scripts are left untouched with a manual command suggestion. Ambiguous/custom integration code still requires review rather than being overwritten. -- The package also exposes **`protect`** directly (runtime exploit guard; its templates live under `dist/protect/`). `setup` invokes it automatically; `scan`, `guide`, `status`, and `mark-build` do not. It writes only local files and auto-wires known stacks — **TanStack Start + Supabase** (patches `src/start.ts` to screen requests, responses and server-function arguments, and the Supabase client to tunnel browser traffic through the guard when the client has the layout it recognises — otherwise the client is left untouched and `protect --check` lists that browser-to-Supabase traffic as not covered; when `src/start.ts` cannot be patched either, the TanStack Start server entry below is used), **TanStack Start** (documented server Fetch entry without requiring Supabase), **Next.js** (scaffolds or composes middleware/proxy and adds request/response checks to supported App Router handlers; a handler it cannot compose is left unchanged and listed by `protect --check` as optional coverage, since the middleware already screens every request), **SvelteKit** (`src/hooks.server.ts`), **Astro** (`src/middleware.ts`), **React Router** (framework mode — a `.server` guard wired from the root route's `middleware` export, the seam Hostinger Horizons and similar builders leave writable), **Nuxt** (`server/middleware/`), **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). Lines marked `!` are optional coverage the guard works without; they do not fail the check. Passing `--demo` seeds a broad sample rule set (for demonstrations, not production). +- The package also exposes **`protect`** directly (runtime exploit guard; its templates live under `dist/protect/`). `setup` invokes it automatically; `scan`, `guide`, `status`, and `mark-build` do not. It writes only local files and auto-wires known stacks — **TanStack Start + Supabase** (patches `src/start.ts` to screen requests, responses and server-function arguments, and the Supabase client to tunnel browser traffic through the guard when the client has the layout it recognises — otherwise the client is left untouched and `protect --check` lists that browser-to-Supabase traffic as not covered; when `src/start.ts` cannot be patched either, the TanStack Start server entry below is used), **TanStack Start** (documented server Fetch entry without requiring Supabase), **Next.js** (scaffolds or composes middleware/proxy and adds request/response checks to supported App Router handlers; a handler it cannot compose is left unchanged and listed by `protect --check` as optional coverage, since the middleware already screens every request), **SvelteKit** (`src/hooks.server.ts`), **Astro** (`src/middleware.ts`), **React Router** (framework mode — a `.server` guard wired from the root route's `middleware` export, the seam Hostinger Horizons and similar builders leave writable), **Nuxt** (`server/middleware/` screens requests and native Node responses), **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). Lines marked `!` are optional coverage the guard works without; they do not fail the check. 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 Patchstack for JavaScript 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. - **Standalone `map` is local unless you pass `--upload`.** It skips dependencies, build output and hidden directories and does not follow external symlinks by default. It reports detected entry points, inputs, sinks, dependency calls and evidence tiers with coverage limitations. Static analysis is best-effort, not a completeness guarantee. `setup` runs this analysis after guard integration and uploads it automatically. - **`map --upload` and `setup` send structural analysis** to `monitor/pulse/input-map/`. The upload includes no source code, file contents or environment variable values. Setup and pre-bundle uploads derive `_patchstack.build_id` from the policy map and write it into the existing guard rules file. A standalone upload outside a build remains unbound and changes no guard file. In any project whose guard has a rules file, unless `.patchstackrc.json` sets `"bundleRules": false`, a `scan` that holds the key and reports successfully outside a build runs the same synchronization as setup: it uploads the map, writes its identity into the guard rules file, fetches the site's current rules and writes them into that same file — keeping the starter signatures, and only when something changed — so a keyless build of the same source (a hosted builder's publish, or any deploy without the key) ships those rules and presents an identity Patchstack already holds. Setup and the development synchronization write the rules there too, under the same condition. In the same runs they POST `monitor/pulse/rules-reader/` with the site credential and store the answer as `_patchstack.rules_reader` in that file: a read-only credential that can fetch this site's rules and report detections for this site, and nothing else — no uploads, no map, no other site — and is the same on every run. A published app without the site credential fetches live rules with it, so a rule released after the publish reaches the running app at its next refresh, without a rebuild. It also reports detections on that credential (`monitor/pulse/detections/`), which Patchstack stores as **unverified** — the credential ships in the app, so such a report is forgeable by anyone who can read it; these events are shown apart and never feed the dashboard's aggregates. Set `PATCHSTACK_API_KEY` in the deployment to report as verified instead. On the first request the live app serves, the guard also POSTs `monitor/pulse/live/` with the public origin it is serving and, when its rules file carries one, the `_patchstack.manifest_checksum` the `prebuild` scan recorded so a server-rendered deployment registers as live without waiting for a browser; it is authenticated by the same credential and sends no request data. Rotating or revoking the site credential retires it. Anyone who can read the project's files can read the site's rules with it, so treat the guard rules file as you would the rest of the app's server code, and never import it into browser code. No recognized routes still means useful import/coverage evidence and is uploaded. API failures are reported without failing a production build. Without a credential nothing is uploaded: a hosted builder's publish holds no key, so its map reaches Patchstack from the workspace — its routine `scan` and its development synchronization — under the same identity, and the publish only writes that identity into its guard. Setup then retrieves Patchstack for JavaScript rules, including delivered response-phase policies, using the same build identity. Only a matching server verdict permits scoped enforcement. The guard rules file is that bundle for a deployed app without the key, current as of the last synchronization; it is server code, not a client bundle, and does not replace runtime rule refresh. A deployment that holds the key fetches with it instead. diff --git a/package.json b/package.json index f139f939..9930042e 100644 --- a/package.json +++ b/package.json @@ -84,6 +84,7 @@ "test:consumers": "node scripts/compat-matrix.mjs", "test:bundled": "node scripts/bundled-consumer.mjs", "test:next": "node scripts/next-consumer.mjs", + "test:frameworks": "node scripts/framework-consumers.mjs", "test:tanstack": "node scripts/tanstack-consumer.mjs", "test:demos": "npm run build && node scripts/run-demos.mjs", "audit:side-effects": "npm run build && node scripts/side-effect-audit.mjs --selftest && node scripts/side-effect-audit.mjs", diff --git a/scripts/framework-consumers.mjs b/scripts/framework-consumers.mjs new file mode 100644 index 00000000..34909454 --- /dev/null +++ b/scripts/framework-consumers.mjs @@ -0,0 +1,272 @@ +import assert from 'node:assert/strict'; +import { spawn, spawnSync } from 'node:child_process'; +import { once } from 'node:events'; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { createServer } from 'node:net'; +import { tmpdir } from 'node:os'; +import { dirname, join, resolve } from 'node:path'; + +const output = `({ label: body.label, sample: 'fixture-private' })`; +const fetchRoute = `async ({ request }) => { + const body = await request.json(); + return Response.json(${output}); +}`; +const fixtures = { + astro: { + dependencies: { astro: '7.4.12', '@astrojs/node': '11.1.13' }, + files: { + 'astro.config.mjs': `import node from '@astrojs/node'; +export default { output: 'server', adapter: node({ mode: 'standalone' }) };`, + 'src/pages/fixture.js': `export const POST = ${fetchRoute};`, + }, + rules: 'src/patchstack.rules.json', + build: ['node_modules/.bin/astro', 'build'], + start: ['dist/server/entry.mjs'], + }, + sveltekit: { + dependencies: { '@sveltejs/kit': '3.3.0', '@sveltejs/adapter-node': '6.0.4', + '@sveltejs/vite-plugin-svelte': '7.3.1', svelte: '5.57.3', vite: '8.3.8' }, + files: { + 'vite.config.js': `import adapter from '@sveltejs/adapter-node'; +import { sveltekit } from '@sveltejs/kit/vite'; +export default { plugins: [sveltekit({ adapter: adapter() })] };`, + 'src/app.html': '%sveltekit.head%%sveltekit.body%', + 'src/routes/fixture/+server.js': `export const POST = ${fetchRoute};`, + }, + rules: 'src/patchstack.rules.json', + build: ['node_modules/vite/bin/vite.js', 'build'], + start: ['build/index.js'], + }, + nuxt: { + dependencies: { nuxt: '4.6.4' }, + files: { + 'nuxt.config.ts': 'export default defineNuxtConfig({ telemetry: false });', + 'app/app.vue': '', + 'server/fixture-stream.ts': `let release: () => void; +export function finishStream() { release(); } +export async function* stream() { + const finished = new Promise(done => { release = done; }); + yield 'data: public\\n\\n'; + await finished; + yield 'data: finished\\n\\n'; +}`, + 'server/routes/stream.get.ts': `import { Readable } from 'node:stream'; +import { sendStream, setResponseHeader } from 'h3'; +import { stream } from '../fixture-stream'; +export default defineEventHandler(event => { + setResponseHeader(event, 'content-type', 'text/event-stream'); + setResponseHeader(event, 'x-fixture', 'fixture-stream-private'); + return sendStream(event, Readable.from(stream())); +});`, + 'server/routes/release.get.ts': `import { finishStream } from '../fixture-stream'; +export default defineEventHandler(() => { finishStream(); return { ok: true }; });`, + 'server/routes/fixture.post.ts': `export default defineEventHandler(async (event) => { + const body = await readBody(event); + return ${output}; +});`, + }, + rules: 'server/middleware/patchstack.rules.json', + build: ['node_modules/.bin/nuxt', 'build'], + start: ['.output/server/index.mjs'], + stream: [''], + }, + 'react-router': { + dependencies: { '@react-router/dev': '8.5.1', '@react-router/serve': '8.5.1', react: '19.3.1', + 'react-dom': '19.3.1', 'react-router': '8.5.1', vite: '8.3.8' }, + files: { + 'vite.config.js': `import { reactRouter } from '@react-router/dev/vite'; +export default { plugins: [reactRouter()] };`, + 'react-router.config.ts': 'export default { ssr: true };', + 'app/root.tsx': `import { Outlet } from 'react-router'; +export default function App() { return ; }`, + 'app/routes.ts': `export default [{ path: 'fixture', file: 'fixture.js' }];`, + 'app/fixture.js': `export const action = ${fetchRoute};`, + }, + rules: 'app/patchstack/patchstack.rules.json', + build: ['node_modules/.bin/react-router', 'build'], + start: ['node_modules/.bin/react-router-serve', './build/server/index.js'], + }, + tanstack: { + dependencies: { '@tanstack/react-start': '1.168.60', '@tanstack/react-router': '1.170.41', + '@vitejs/plugin-react': '6.3.0', nitro: '3.0.261103-rc', react: '19.3.1', 'react-dom': '19.3.1', vite: '8.3.8' }, + files: { + 'vite.config.ts': `import { defineConfig } from 'vite'; +import { tanstackStart } from '@tanstack/react-start/plugin/vite'; +import react from '@vitejs/plugin-react'; +import { nitro } from 'nitro/vite'; +export default defineConfig({ plugins: [tanstackStart(), react(), nitro({ preset: 'node-server' })] });`, + 'tsconfig.json': JSON.stringify({ compilerOptions: { + jsx: 'react-jsx', module: 'ESNext', moduleResolution: 'Bundler', target: 'ES2022', skipLibCheck: true, + } }), + 'src/router.tsx': `import { createRouter } from '@tanstack/react-router'; +import { routeTree } from './routeTree.gen'; +export function getRouter() { return createRouter({ routeTree }); }`, + 'src/routes/__root.tsx': `import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router'; +export const Route = createRootRoute({ + component: () => , +});`, + 'src/routes/fixture.ts': `import { createFileRoute } from '@tanstack/react-router'; +export const Route = createFileRoute('/fixture')({ server: { handlers: { POST: ${fetchRoute} } } });`, + }, + rules: 'src/patchstack/rules.json', + build: ['node_modules/.bin/vite', 'build'], + start: ['.output/server/index.mjs'], + }, + nestjs: { + dependencies: { '@nestjs/core': '12.5.1', '@nestjs/common': '12.5.1', + '@nestjs/platform-express': '12.5.1', 'reflect-metadata': '0.2.2', rxjs: '7.8.2' }, + files: { + 'server.cjs': `require('reflect-metadata'); +const { NestFactory } = require('@nestjs/core'); +const { Module, Controller, Post, Body, HttpCode } = require('@nestjs/common'); +class Fixture { + submit(body) { return ${output}; } +} +const method = Object.getOwnPropertyDescriptor(Fixture.prototype, 'submit'); +Controller()(Fixture); +Post('fixture')(Fixture.prototype, 'submit', method); +HttpCode(200)(Fixture.prototype, 'submit', method); +Body()(Fixture.prototype, 'submit', 0); +class AppModule {} +Module({ controllers: [Fixture] })(AppModule); +async function main() { + const app = await NestFactory.create(AppModule); + await app.listen(Number(process.env.PORT), '127.0.0.1'); +} +main();`, + }, + rules: 'patchstack/rules.json', + start: ['server.cjs'], + }, +}; + +function fastifyFixture(format) { + const commonJs = format === 'cjs'; + const entry = commonJs ? 'server.cjs' : 'server.mjs'; + return { + dependencies: { fastify: '5.12.1' }, + files: { [entry]: ` +${commonJs ? "const { fastify } = require('fastify');" : "import defaultFastify, { fastify } from 'fastify';"} +${commonJs ? "" : "if (defaultFastify !== fastify) throw new Error('Inconsistent Fastify exports');"} +${commonJs ? "const { Readable } = require('node:stream');" : "import { Readable } from 'node:stream';"} +const app = fastify(); +let finishStream; +app.get('/release', async () => { finishStream(); return { ok: true }; }); +app.get('/stream', async (request, reply) => { + const release = new Promise(resolve => { finishStream = resolve; }); + const chunks = async function* () { + yield 'data: public\\n\\n'; + await release; + yield 'data: finished\\n\\n'; + }; + return reply.type(request.query.text ? 'text/plain' : 'text/event-stream').header('x-fixture', 'fixture-stream-private') + .send(Readable.from(chunks())); +}); +app.post('/fixture', async ({ body }) => ${output}); +app.listen({ port: Number(process.env.PORT), host: '127.0.0.1' }); +` }, + rules: 'patchstack/rules.json', + start: [entry], + stream: ['', '?text=1'], + }; +} + +fixtures.fastify = fastifyFixture('cjs'); +// Run against an npm pack artifact on a Unix host. Framework packages are pinned per fixture. +const [name, tarball] = process.argv.slice(2); +assert.ok(Object.hasOwn(fixtures, name) && tarball, `Usage: node scripts/framework-consumers.mjs <${Object.keys(fixtures).join('|')}> `); +const fixture = fixtures[name]; +const cwd = mkdtempSync(join(tmpdir(), 'ps-framework-')); +const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('PATCHSTACK_') && key !== 'NODE_OPTIONS')); +Object.assign(env, { ASTRO_TELEMETRY_DISABLED: '1', NUXT_TELEMETRY_DISABLED: '1', CI: '1', HOST: '127.0.0.1' }); +const put = (file, source) => { + mkdirSync(dirname(join(cwd, file)), { recursive: true }); + writeFileSync(join(cwd, file), source); +}; +function run(command, args) { + const child = spawnSync(command, args, { cwd, env, encoding: 'utf8', timeout: 180_000 }); + assert.equal(child.status, 0, [child.error?.message, child.stdout, child.stderr].join('\n').replaceAll(cwd, '')); +} +async function check(protectedApp) { + const listener = createServer().listen(0, '127.0.0.1'); + await once(listener, 'listening'); + const port = listener.address().port; + await new Promise(done => listener.close(done)); + const processEnv = { ...env, PORT: String(port), ORIGIN: `http://127.0.0.1:${port}` }; + const app = spawn(process.execPath, fixture.start, { cwd, env: processEnv, stdio: ['ignore', 'pipe', 'pipe'] }); + let log = ''; + for (const stream of [app.stdout, app.stderr]) stream.on('data', part => { log += part; }); + const post = label => fetch(processEnv.ORIGIN + '/fixture', { + method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ label }), + signal: AbortSignal.timeout(3000), + }); + try { + let normal; + for (let attempt = 0; attempt < 200 && app.exitCode === null; attempt++) { + try { normal = await post('ordinary'); break; } catch { await new Promise(done => setTimeout(done, 100)); } + } + assert.equal(normal?.status, 200, log.replaceAll(cwd, '')); + const result = await normal.json(); + assert.equal(result.label, 'ordinary'); + assert.equal(typeof result.sample, 'string'); + if (protectedApp) assert.doesNotMatch(result.sample, /fixture-private/); + else assert.equal(result.sample, 'fixture-private'); + assert.equal((await post('fixture-block')).status, protectedApp ? 403 : 200); + if (fixture.stream) { + for (const suffix of fixture.stream) { + const stream = await fetch(processEnv.ORIGIN + '/stream' + suffix, { signal: AbortSignal.timeout(3000) }); + assert.equal(stream.status, 200); + const header = stream.headers.get('x-fixture'); + assert.equal(typeof header, 'string'); + if (protectedApp) assert.doesNotMatch(header, /fixture-stream-private/); + else assert.equal(header, 'fixture-stream-private'); + const reader = stream.body.getReader(); + const decoder = new TextDecoder(); + let first = ''; + while (!first.endsWith('\n\n')) { + const chunk = await reader.read(); + assert.equal(chunk.done, false); + first += decoder.decode(chunk.value); + } + assert.equal(first, 'data: public\n\n'); + const release = await fetch(processEnv.ORIGIN + '/release', { signal: AbortSignal.timeout(3000) }); + assert.equal(release.status, 200); + await release.text(); + let rest = ''; + for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) rest += decoder.decode(chunk.value); + assert.equal(rest, 'data: finished\n\n'); + } + } + } finally { + if (app.exitCode === null) { + const exited = once(app, 'exit'); + const timer = setTimeout(() => app.kill('SIGKILL'), 3000); + app.kill('SIGTERM'); + try { await exited; } finally { clearTimeout(timer); } + } + } +} +try { + put('package.json', JSON.stringify({ name: 'framework-fixture', private: true, type: 'module', + dependencies: { ...fixture.dependencies, '@patchstack/connect': `file:${resolve(tarball)}` } })); + for (const [file, source] of Object.entries(fixture.files)) put(file, source); + run('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts']); + if (fixture.build) run(process.execPath, fixture.build); + await check(false); + const cli = 'node_modules/@patchstack/connect/dist/cli.js'; + run(process.execPath, [cli, 'protect']); + run(process.execPath, [cli, 'protect', '--check']); + readFileSync(join(cwd, fixture.rules)); + put(fixture.rules, JSON.stringify({ firewall: [ + { id: 'fixture-request', rule_v2: [{ parameter: 'post.label', match: { type: 'equals', value: 'fixture-block' } }] }, + { id: 'fixture-response', phase: 'response', action: 'redact', when: { path: '/fixture', method: 'POST' }, + rule_v2: [{ parameter: 'response.body', match: { type: 'contains', value: 'fixture-private' } }] }, + { id: 'fixture-stream-header', phase: 'response', action: 'redact', when: { path: '/stream' }, + rule_v2: [{ parameter: 'response.header.x-fixture', match: { type: 'regex', value: '/fixture-stream-private/' } }] }, + ], whitelists: [], whitelist_keys: {} })); + if (fixture.build) run(process.execPath, fixture.build); + await check(true); + console.log(`PASS ${name}: HTTP request screening, normal body parsing and response redaction${fixture.stream ? ' including stream headers' : ''}`); +} finally { + rmSync(cwd, { recursive: true, force: true }); +} diff --git a/src/protect/install/template-upgrade.ts b/src/protect/install/template-upgrade.ts index c05afad5..3dee1561 100644 --- a/src/protect/install/template-upgrade.ts +++ b/src/protect/install/template-upgrade.ts @@ -5,20 +5,32 @@ import { read, log, templatesDir } from './util.js'; import { writeProjectFileSync } from '../../safe-file.js'; // Fingerprints of public generated helpers. Only the baked site identity is excluded. -const PREVIOUS: Record = { +const PREVIOUS: Record = { 'generic-guard.ts': '2c6bb8324b909e646049c36725704b474a8bfb1b6849c392eb3462eed83727e9', 'generic-guard.js': '42357bcf0cb0541e584821d03e06ced28f98d4ef91a76a50e39008ef18c63709', 'generic-guard.cjs': '8de21893474a3139eff9e8fc48a0c13e976e64421281db9e8e93b0c0549361b8', 'express-guard.ts': '6c30cc82b7cbd3fee62d423fcb20b27eba1d6cc1ed054efcf9d64eb360bc7b17', 'express-guard.js': 'bce7c76a061297621791d4ebf838449e3880d05f333588fed7bf88431d1e712e', 'express-guard.cjs': '3a6430f00fc159c28a897e700cc492c306f39b556f0f4cb4b1e718993b6c40b4', - 'fastify-plugin.ts': '5d606cb8f8f2e6fe35b9d377c5568c5a2090a81af9f0acb219ebc15a713792e9', - 'fastify-plugin.js': '03327d437513571d53554ca34c84ba170ebeebb5e89c2602ae340fb82178ab48', - 'fastify-plugin.cjs': 'b3754bf023ebb5f2a22e0a95cfe74bb783034ec3db9ce61a3e7202237e09e1dd', + 'fastify-plugin.ts': [ + '5d606cb8f8f2e6fe35b9d377c5568c5a2090a81af9f0acb219ebc15a713792e9', + '1b995704a608397fd6e2fe47b4e46461299cb444110b2988fd9ebedee9804d05', + ], + 'fastify-plugin.js': [ + '03327d437513571d53554ca34c84ba170ebeebb5e89c2602ae340fb82178ab48', + '71bcd3699bad8fba0fa347332c6739219d2e3cf7a594a85442fe853f23ab5d53', + ], + 'fastify-plugin.cjs': [ + 'b3754bf023ebb5f2a22e0a95cfe74bb783034ec3db9ce61a3e7202237e09e1dd', + 'fd90ef3a4be1234307e3b631d1ac7e898b24a025043c928b7ae48189f19af45d', + ], 'guard.ts': '270e29769f5a7b3ab70ee39970be5a4e150e1b3949877687dca1ed83596afae7', 'sveltekit-hooks.ts': '0a68389ac9018dc0ab5805356ad78301f039cb4c701bf642e7f986cc959da990', 'astro-middleware.ts': 'f217e302fb7019de451c7538e9266a5ce38aa6a6651072b6291d4593b31f60ce', - 'nuxt-middleware.ts': 'e377c48cc8c08d20c61c6119bb5f4c8991f0eed3ebd31310b8a0fc6eb5505e4e', + 'nuxt-middleware.ts': [ + 'e377c48cc8c08d20c61c6119bb5f4c8991f0eed3ebd31310b8a0fc6eb5505e4e', + 'c4d1cf018db3d8c25d09b4b042c24059db97af5d0ea1847ddb75ab8f6baa8eae', + ], 'next-middleware.ts': '65c163cdb2ddda4fe53c1a3cd20aa6ab63ad7595a66985d9141d595374ecfab3', 'next-guard.ts': 'e37c4d67619df9d850a7d94b567bd76841b6ac8e774a5b442689482f5374c451', }; @@ -35,7 +47,9 @@ export function installTemplate(cwd: string, file: string, template: string): bo } const previous = read(target); if (normalized(previous) === normalized(next)) return false; - if (createHash('sha256').update(normalized(previous)).digest('hex') !== PREVIOUS[template]) { + const checksum = createHash('sha256').update(normalized(previous)).digest('hex'); + const known = PREVIOUS[template]; + if (typeof known === 'string' ? checksum !== known : !known?.includes(checksum)) { log(`${file} is customized or unrecognized — preserved; review its request/response wiring and rule-refresh settings manually.`); return false; } diff --git a/src/protect/protect.d.ts b/src/protect/protect.d.ts index dfa64270..49b0a4a1 100644 --- a/src/protect/protect.d.ts +++ b/src/protect/protect.d.ts @@ -52,6 +52,9 @@ export interface Protection { * and `content-length`. */ screenResponse(response: Response, request?: Request, ...hostArgs: unknown[]): Promise; + /** Attach screening before a native Node ServerResponse sends its headers. + * Set headersOnly when the host must pass the response body through without buffering. */ + screenNodeResponse(response: unknown, request?: Request, options?: { headersOnly?: boolean }): void; express(options?: { screenResponses?: boolean }): (req: unknown, res: unknown, next: () => void) => void; /** * Node / Connect middleware that reads the request body itself and exposes it as `req.body`. diff --git a/src/protect/runtime.js b/src/protect/runtime.js index 441bfcfd..e06429a6 100644 --- a/src/protect/runtime.js +++ b/src/protect/runtime.js @@ -1148,7 +1148,7 @@ export async function createProtection(options = {}) { // Wrap a Node ServerResponse so its (buffered, text) body is screened before it's sent. // Opt-in (buffering can delay a streamed response); over 512 KiB it stops buffering and // passes through unscanned. - const wrapNodeResponse = (res, reqCtx) => { + const wrapNodeResponse = (res, reqCtx, headersOnly = false) => { const origWrite = res.write.bind(res); const origEnd = res.end.bind(res); // The response's own header operations, for this wrapper's use. While a `writeHead` is held the @@ -1163,7 +1163,7 @@ export async function createProtection(options = {}) { const reallySent = () => Boolean(sentAccessor ? sentAccessor.call(res) : sentValue); const chunks = []; let size = 0; - let overflow = false; + let passBody = false; let withheld = false; // Whether the rules decided on headers alone have already been run for this response. let headScreened = false; @@ -1530,20 +1530,34 @@ export async function createProtection(options = {}) { for (const c of chunks) origWrite(c); chunks.length = 0; origWrite(buf); - overflow = true; + passBody = true; recordSkip('response', 'body-cap', { bytes: size }); return; } chunks.push(buf); }; + const skipBody = (reason, cb) => { + const bodyless = res.req?.method === 'HEAD' || res.statusCode < 200 || [204, 205, 304].includes(res.statusCode); + if (reason && !bodyless) recordSkip('response', reason); + const unread = screenUnreadHead(); + if (unread?.withhold) return sendWithheld(cb); + sendHead(unread); + passBody = true; + }; res.write = function (chunk, enc, cb) { + if (!withheld && !passBody && chunks.length === 0) { + const value = effectiveHead().headers['content-type']; + const contentType = Array.isArray(value) ? value[0] : value; + if (baseContentType(contentType) === 'text/event-stream') skipBody('live-stream'); + else if (headersOnly) skipBody('streamed-body'); + } if (withheld) { if (typeof enc === 'function') enc(); else if (typeof cb === 'function') cb(); return true; } - if (overflow) return origWrite(chunk, enc, cb); + if (passBody) return origWrite(chunk, enc, cb); collect(chunk, enc); if (typeof enc === 'function') enc(); else if (typeof cb === 'function') cb(); @@ -1557,14 +1571,18 @@ export async function createProtection(options = {}) { return res; } - if (overflow) { if (chunk != null) origWrite(chunk, enc); return origEnd(cb); } + if (!passBody && headersOnly) { + skipBody(chunk == null ? null : 'streamed-body', cb); + if (withheld) return res; + } + if (passBody) return origEnd(chunk, enc, cb); collect(chunk, enc); if (withheld) { if (typeof cb === 'function') cb(); return res; } - if (overflow) return origEnd(cb); // collect just flushed head + final chunk on overflow + if (passBody) return origEnd(cb); // collect flushed the head and final chunk on overflow hardenOnce(); const passThrough = (changes) => { @@ -1875,6 +1893,15 @@ export async function createProtection(options = {}) { screenResponse: (response, request, ...hostArgs) => screenResp(response, request ? reqContextFromFetch(request, clientForResponse(request, hostArgs)) : undefined), + screenNodeResponse(response, request, options) { + if (!nodeHttp?.ServerResponse || !(response instanceof nodeHttp.ServerResponse)) { + recordSkip('response', 'unsupported-node-response'); + return; + } + wrapNodeResponse(response, request ? reqContextFromFetch(request, clientForResponse(request, [])) : undefined, + options?.headersOnly === true); + }, + // (request) => Response | null (null = allow, caller proceeds). Request phase only. fetchGuard() { return async (request, ...hostArgs) => { diff --git a/src/protect/templates/fastify-plugin.cjs b/src/protect/templates/fastify-plugin.cjs index 519dfd44..c38de635 100644 --- a/src/protect/templates/fastify-plugin.cjs +++ b/src/protect/templates/fastify-plugin.cjs @@ -156,19 +156,9 @@ async function patchstackFastify(fastify) { }); fastify.addHook("onSend", async (request, reply, payload) => { - // Do not consume streams, hijacked responses, or bodyless status codes. - if ((typeof payload !== "string" && !Buffer.isBuffer(payload)) - || request.method === "HEAD" || reply.statusCode < 200 || [204, 205, 304].includes(reply.statusCode)) return payload; const protection = await getProtection().catch(psStepAside); if (!protection) return payload; try { - const headers = new Headers(); - for (const [name, value] of Object.entries(reply.getHeaders())) { - for (const item of Array.isArray(value) ? value : [value]) { - if (item !== undefined) headers.append(name, String(item)); - } - } - const original = new Response(typeof payload === "string" ? payload : new Uint8Array(payload).buffer, { status: reply.statusCode, headers }); // A request the Request constructor refuses still has its response screened, by every rule that does // not need the request to decide. let context; @@ -178,6 +168,19 @@ async function patchstackFastify(fastify) { } catch { context = undefined; } + if ((typeof payload !== "string" && !Buffer.isBuffer(payload)) + || request.method === "HEAD" || reply.statusCode < 200 || [204, 205, 304].includes(reply.statusCode)) { + // The Node guard can harden headers and account for skipped bodies without reading the stream here. + protection.screenNodeResponse(reply.raw, context, { headersOnly: true }); + return payload; + } + const headers = new Headers(); + for (const [name, value] of Object.entries(reply.getHeaders())) { + for (const item of Array.isArray(value) ? value : [value]) { + if (item !== undefined) headers.append(name, String(item)); + } + } + const original = new Response(typeof payload === "string" ? payload : new Uint8Array(payload).buffer, { status: reply.statusCode, headers }); const screened = await protection.screenResponse(original, context); if (screened === original) return payload; const body = Buffer.from(await screened.arrayBuffer()); diff --git a/src/protect/templates/fastify-plugin.js b/src/protect/templates/fastify-plugin.js index 96408bb0..ec56e659 100644 --- a/src/protect/templates/fastify-plugin.js +++ b/src/protect/templates/fastify-plugin.js @@ -157,19 +157,9 @@ export async function patchstackFastify(fastify) { }); fastify.addHook("onSend", async (request, reply, payload) => { - // Do not consume streams, hijacked responses, or bodyless status codes. - if ((typeof payload !== "string" && !Buffer.isBuffer(payload)) - || request.method === "HEAD" || reply.statusCode < 200 || [204, 205, 304].includes(reply.statusCode)) return payload; const protection = await getProtection().catch(psStepAside); if (!protection) return payload; try { - const headers = new Headers(); - for (const [name, value] of Object.entries(reply.getHeaders())) { - for (const item of Array.isArray(value) ? value : [value]) { - if (item !== undefined) headers.append(name, String(item)); - } - } - const original = new Response(typeof payload === "string" ? payload : new Uint8Array(payload).buffer, { status: reply.statusCode, headers }); // A request the Request constructor refuses still has its response screened, by every rule that does // not need the request to decide. let context; @@ -179,6 +169,19 @@ export async function patchstackFastify(fastify) { } catch { context = undefined; } + if ((typeof payload !== "string" && !Buffer.isBuffer(payload)) + || request.method === "HEAD" || reply.statusCode < 200 || [204, 205, 304].includes(reply.statusCode)) { + // The Node guard can harden headers and account for skipped bodies without reading the stream here. + protection.screenNodeResponse(reply.raw, context, { headersOnly: true }); + return payload; + } + const headers = new Headers(); + for (const [name, value] of Object.entries(reply.getHeaders())) { + for (const item of Array.isArray(value) ? value : [value]) { + if (item !== undefined) headers.append(name, String(item)); + } + } + const original = new Response(typeof payload === "string" ? payload : new Uint8Array(payload).buffer, { status: reply.statusCode, headers }); const screened = await protection.screenResponse(original, context); if (screened === original) return payload; const body = Buffer.from(await screened.arrayBuffer()); diff --git a/src/protect/templates/fastify-plugin.ts b/src/protect/templates/fastify-plugin.ts index 7a4b8090..09ed3364 100644 --- a/src/protect/templates/fastify-plugin.ts +++ b/src/protect/templates/fastify-plugin.ts @@ -155,19 +155,9 @@ export async function patchstackFastify(fastify: any) { }); fastify.addHook("onSend", async (request: any, reply: any, payload: any) => { - // Do not consume streams, hijacked responses, or bodyless status codes. - if ((typeof payload !== "string" && !Buffer.isBuffer(payload)) - || request.method === "HEAD" || reply.statusCode < 200 || [204, 205, 304].includes(reply.statusCode)) return payload; const protection = await getProtection().catch(psStepAside); if (!protection) return payload; try { - const headers = new Headers(); - for (const [name, value] of Object.entries(reply.getHeaders())) { - for (const item of Array.isArray(value) ? value : [value]) { - if (item !== undefined) headers.append(name, String(item)); - } - } - const original = new Response(typeof payload === "string" ? payload : new Uint8Array(payload).buffer, { status: reply.statusCode, headers }); // A request the Request constructor refuses still has its response screened, by every rule that does // not need the request to decide. let context: Request | undefined; @@ -177,6 +167,19 @@ export async function patchstackFastify(fastify: any) { } catch { context = undefined; } + if ((typeof payload !== "string" && !Buffer.isBuffer(payload)) + || request.method === "HEAD" || reply.statusCode < 200 || [204, 205, 304].includes(reply.statusCode)) { + // The Node guard can harden headers and account for skipped bodies without reading the stream here. + protection.screenNodeResponse(reply.raw, context, { headersOnly: true }); + return payload; + } + const headers = new Headers(); + for (const [name, value] of Object.entries(reply.getHeaders())) { + for (const item of Array.isArray(value) ? value : [value]) { + if (item !== undefined) headers.append(name, String(item)); + } + } + const original = new Response(typeof payload === "string" ? payload : new Uint8Array(payload).buffer, { status: reply.statusCode, headers }); const screened = await protection.screenResponse(original, context); if (screened === original) return payload; const body = Buffer.from(await screened.arrayBuffer()); diff --git a/src/protect/templates/nuxt-middleware.ts b/src/protect/templates/nuxt-middleware.ts index e1392659..791b3147 100644 --- a/src/protect/templates/nuxt-middleware.ts +++ b/src/protect/templates/nuxt-middleware.ts @@ -1,5 +1,5 @@ // Patchstack runtime guard for Nuxt / Nitro — server middleware. Managed by `patchstack-connect protect`. -// Runs the request-phase WAF (+ egress SSRF) on every request. Nuxt runs each file in +// Screens requests and native Node responses (+ egress SSRF). Nuxt runs each file in // `server/middleware/` as independent middleware, so this file coexists with your own. import { defineEventHandler, getRequestURL, readRawBody, setResponseStatus, setResponseHeader } from "h3"; import { createProtection } from "@patchstack/connect/protect"; @@ -70,13 +70,14 @@ export default defineEventHandler(async (event) => { const method = event.method ?? "GET"; // readRawBody caches on the event, so your route handlers can still read the body. const body = method !== "GET" && method !== "HEAD" ? await readRawBody(event) : undefined; - const blocked = await protection - .fetchGuard()(new Request(getRequestURL(event), { method, headers: event.headers, body: body ?? undefined })); + const request = new Request(getRequestURL(event), { method, headers: event.headers, body: body ?? undefined }); + const blocked = await protection.fetchGuard()(request); if (blocked) { setResponseStatus(event, blocked.status); const contentType = blocked.headers.get("content-type"); if (contentType) setResponseHeader(event, "content-type", contentType); return blocked.text(); // 403 — blocked before it reaches your route } + protection.screenNodeResponse(event.node?.res, request); }); // #endregion patchstack-nuxt diff --git a/tests/protect/a-guard-without-its-fallback-file.test.ts b/tests/protect/a-guard-without-its-fallback-file.test.ts index 7ba9f2f2..9b783d73 100644 --- a/tests/protect/a-guard-without-its-fallback-file.test.ts +++ b/tests/protect/a-guard-without-its-fallback-file.test.ts @@ -53,7 +53,7 @@ async function loadGuard(name: string, rules: string | null): Promise async () => null, screenResponse: async (response) => response }'; + ' fetchGuard: () => async () => null, screenResponse: async (response) => response, screenNodeResponse: () => {} }'; const record = `async (options) => { (globalThis.__psOptions ??= []).push(options); return ${usable}; }`; const stub = commonjs ? 'stub.cjs' : 'stub.mjs'; writeFileSync(