From 44f92ac4c46a64a59047dcb76d79c945fb76e0a6 Mon Sep 17 00:00:00 2001 From: Amp Date: Thu, 19 Nov 2026 15:35:13 +0000 Subject: [PATCH] Wire the Express guard when the body parser shares its app.use call Setup only recognised a body parser on a line that started `app.use(` and went straight into `json(`/`urlencoded(`. A path-scoped parser (`app.use('/api', express.json())`), a parser after other middleware (`app.use(cors(), express.json())`) and a call split over several lines were all missed, so setup reported "body-parser anchor not found" and left the app unwired. The anchor now accepts a mount path and other arguments before the parser, call-expression middleware after it, and calls that span lines. A parser followed by a router in the same call (`app.use('/api', express.json(), router)`) is still left alone: the router runs before anything registered after that call, so the guard cannot be added there safely. The manual hint now says to give the parser its own `app.use` in that case. A path-scoped parser on its own is no longer counted as a route above the guard. The "routes registered before the guard" hint said to move the routes below the guard, which is wrong when the line is middleware such as `app.use(securityHeaders)`. It now says the guard must be registered before that line (with the body parser above it), or the line moved below the guard. AGENT-INSTALL.md now says how to run tests with the guard installed: `PATCHSTACK_MODE=dry-run` and `PATCHSTACK_TELEMETRY=off`, keeping the registration unconditional so `protect --check` still sees it. Amp-Thread-ID: https://ampcode.com/threads/T-2e659ca3-7bd0-4d70-b3d3-09638251060b Co-authored-by: Danilo Radovic --- AGENT-INSTALL.md | 5 +++ src/protect/install/adapters/express.ts | 20 +++++++++-- src/protect/install/register.ts | 48 +++++++++++++++++-------- tests/protect/adapters.test.ts | 41 +++++++++++++++++++++ 4 files changed, 97 insertions(+), 17 deletions(-) diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md index ffb0f4cf..c43df127 100644 --- a/AGENT-INSTALL.md +++ b/AGENT-INSTALL.md @@ -770,6 +770,11 @@ would have stopped while it is still in dry-run. Two separate paths, with differ `protect --check` still accepts as the guard it wrote. Any other change to the file makes it a custom guard, which the check cannot vouch for. + **In automated tests**, the guard has no switch that removes it. Run the tests with + `PATCHSTACK_MODE=dry-run`, so it blocks nothing, and `PATCHSTACK_TELEMETRY=off`, so it reports nothing. + Keep `app.use(patchstackMiddleware)` unconditional: `protect --check` counts only a guard registered in + the app's own scope, so registering it inside an `if` reads as unprotected. + `protection.detectionReporting` names the current state locally, so a guard that is not reporting says which reason applies: `on`, `disabled-by-config`, `disabled-by-telemetry-opt-out`, `not-enrolled`, `no-managed-rules`, or `unavailable-no-credential`. diff --git a/src/protect/install/adapters/express.ts b/src/protect/install/adapters/express.ts index 3e4314e0..50aba544 100644 --- a/src/protect/install/adapters/express.ts +++ b/src/protect/install/adapters/express.ts @@ -6,11 +6,25 @@ import { findAppInstance } from '../find-app.js'; import { wireRegister, verifyRegister, type RegisterSpec } from '../register.js'; import type { Adapter } from '../types.js'; +// Balanced parentheses up to three levels deep, so a parser's options (`verify: (req, res, buf) => ...`) +// and the arguments around it are read as whole arguments and never run past the `app.use(` call. +const NESTED = '\\((?:[^()]|\\((?:[^()]|\\([^()]*\\))*\\))*\\)'; +const BALANCED = `(?:[^()]|${NESTED})*`; +const CALL = `[A-Za-z_$][\\w$]*(?:\\.[A-Za-z_$][\\w$]*)*\\(${BALANCED}\\)`; + // A body parser that populates req.body, in any of the shapes AI builders emit: express.json() / // express.urlencoded(), body-parser's bodyParser.json() / .urlencoded(), an aliased parser // (any `x.json(` / `x.urlencoded(`), or a destructured `json(` / `urlencoded(`. +// +// The parser may follow a mount path or other middleware in the same call, and the call may span lines. +// Only call expressions (`cors()`) may follow it: a bare identifier or inline handler after the parser can +// be a router the parser feeds, which the guard cannot be registered after. Matched from the start of the +// text, so callers pass the source from the line being asked about onwards. const bodyParserRe = (appVar: string) => - new RegExp(`^\\s*${appVar}\\.use\\(\\s*(?:[A-Za-z_$][\\w$]*\\.)?(?:json|urlencoded)\\(`, 'm'); + new RegExp( + `^\\s*${appVar}\\.use\\(\\s*(?:${BALANCED},\\s*)?(?:[A-Za-z_$][\\w$]*\\.)?(?:json|urlencoded)\\(${BALANCED}\\)` + + `(?:\\s*,\\s*${CALL})*\\s*,?\\s*\\)`, + ); const SPEC: RegisterSpec = { appRe: /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*express\(\)/, @@ -22,7 +36,9 @@ const SPEC: RegisterSpec = { callAfter: bodyParserRe, requireCallAfter: true, label: 'Express app', - manualHint: 'add `app.use(patchstackMiddleware)` after your body parser (express.json/urlencoded or body-parser) and before the routes', + manualHint: + 'add `app.use(patchstackMiddleware)` after your body parser (express.json/urlencoded or body-parser) and before the routes; ' + + 'if the parser and a router share one `app.use(...)` call, give the parser its own `app.use` above the guard', }; export const expressAdapter: Adapter = { diff --git a/src/protect/install/register.ts b/src/protect/install/register.ts index b357e187..c792ea01 100644 --- a/src/protect/install/register.ts +++ b/src/protect/install/register.ts @@ -40,19 +40,38 @@ const routeRegistration = (appVar: string) => * Route lines that come before `guardIndex`, if any. * * Both prefixed and bare router mounts count. An identifier passed to `app.use` can be a router, so it - * cannot safely be treated as a non-terminating middleware merely because the prefix is absent. + * cannot safely be treated as a non-terminating middleware merely because the prefix is absent. A + * statement that matches `anchor` (a path-scoped body parser, `app.use('/api', express.json())`) is not a + * route: it registers no handler. */ -export function routesBefore(source: string, appVar: string, guardIndex: number): number[] { +export function routesBefore(source: string, appVar: string, guardIndex: number, anchor?: RegExp): number[] { if (guardIndex < 0) return []; const pattern = routeRegistration(appVar); + const lines = source.split('\n'); - return source - .split('\n') + return lines .map((line, index) => ({ line, index })) - .filter(({ line, index }) => index < guardIndex && pattern.test(line)) + .filter(({ line, index }) => index < guardIndex && pattern.test(line) && !(anchor && anchoredAt(lines, index, anchor))) .map(({ index }) => index + 1); // 1-based, for a message a person reads } +/** How far below a statement's first line an anchor may still be matched: one `app.use(...)` call. */ +const ANCHOR_SPAN = 40; + +/** + * Does the statement starting on line `index` match `anchor`? Read from that line onwards, so a call that + * spans several lines is matched whole; the anchor itself decides where the call ends. + */ +function anchoredAt(lines: string[], index: number, anchor: RegExp): boolean { + return anchor.test(lines.slice(index, index + ANCHOR_SPAN).join('\n')); +} + +/** Where a route or middleware sits above the guard: the same advice is right for both. */ +function earlyRouteAdvice(lines: number[], call: string): string { + const one = lines.length === 1; + return `the guard must be registered before line${one ? '' : 's'} ${lines.join(', ')}: move \`${call}\` and your body parser above ${one ? 'it' : 'them'}, or move ${one ? 'it' : 'them'} below the guard`; +} + 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 @@ -161,7 +180,7 @@ function wiringState( ); const appIndex = maskedLines.findIndex((line) => spec.appRe.test(line)); const anchor = spec.callAfter ? spec.callAfter(appVar) : null; - const anchorIndex = anchor ? maskedLines.reduce((last, line, index) => anchor.test(line) ? index : last, -1) : -1; + const anchorIndex = anchor ? maskedLines.reduce((last, _line, index) => anchoredAt(maskedLines, index, anchor) ? index : last, -1) : -1; return { importAtTopLevel: importIndex !== -1 && isTopLevelLine(code, importIndex), @@ -285,7 +304,7 @@ export function wireRegister(cwd: string, opts: WireOptions, spec: RegisterSpec) if ( spec.requireCallAfter && requiredAnchor && - !sourceLines.some((line, index) => index > sourceAppIdx && requiredAnchor.test(line)) + !sourceLines.some((_line, index) => index > sourceAppIdx && anchoredAt(sourceLines, index, requiredAnchor)) ) { log(`${entry.relPath} body-parser anchor not found — scaffolded guard; ${spec.manualHint}`); return { ok: true, changed }; @@ -313,7 +332,7 @@ export function wireRegister(cwd: string, opts: WireOptions, spec: RegisterSpec) if (appIdx !== -1 && !state.callInAppScope) { const preferred = spec.callAfter?.(entry.appVar); const preferredIdx = preferred - ? lines.reduce((last, line, index) => index > appIdx && preferred.test(line) + ? lines.reduce((last, _line, index) => index > appIdx && anchoredAt(lines, index, preferred) && inSameBlockAfter(lines.join('\n'), appIdx, index) ? index : last, -1) : -1; const callIdx = preferredIdx === -1 ? appIdx : preferredIdx; @@ -346,12 +365,11 @@ export function wireRegister(cwd: string, opts: WireOptions, spec: RegisterSpec) // the guard, only by moving the route. if (spec.callAfter) { const guardIndex = lines.findIndex((line) => line.includes(spec.call(entry.appVar))); - const early = routesBefore(patched, entry.appVar, guardIndex); + const early = routesBefore(patched, entry.appVar, guardIndex, spec.callAfter(entry.appVar)); if (early.length > 0) { log( - `${entry.relPath}: ${early.length} route${early.length === 1 ? '' : 's'} registered before the guard ` + - `(line${early.length === 1 ? '' : 's'} ${early.join(', ')}) — those are not screened. ` + - 'Move them below the guard, or move your body parser above them.', + `${entry.relPath}: ${early.length} route or middleware registration${early.length === 1 ? '' : 's'} run before the guard ` + + `and ${early.length === 1 ? 'is' : 'are'} not screened — ${earlyRouteAdvice(early, spec.call(entry.appVar).trim())}.`, ); } } @@ -405,7 +423,7 @@ function serverIsGuarded( const state = wiringState(source, spec, server.appVar, server.relPath, { cwd, guardDir }); if (!state.importAtTopLevel || !state.callInAppScope || !state.ordered) return false; - return !spec.callAfter || routesBefore(source, server.appVar, state.callIndex).length === 0; + return !spec.callAfter || routesBefore(source, server.appVar, state.callIndex, spec.callAfter(server.appVar)).length === 0; } export function verifyRegister(cwd: string, spec: RegisterSpec): VerifyResult { @@ -423,7 +441,7 @@ export function verifyRegister(cwd: string, spec: RegisterSpec): VerifyResult { // "After the parser" was the only ordering checked, and it is only half the question. A route registered // above the guard is served without it, so reporting the app fully wired would name protection that this // route does not have. - const early = spec.callAfter && entry ? routesBefore(entrySource, entry.appVar, state.callIndex) : []; + const early = spec.callAfter && entry ? routesBefore(entrySource, entry.appVar, state.callIndex, spec.callAfter(entry.appVar)) : []; const noEarlyRoutes = early.length === 0; // A project can start more than one server, and a guard on one is not a guard on the other. Each is asked @@ -457,7 +475,7 @@ export function verifyRegister(cwd: string, spec: RegisterSpec): VerifyResult { ok: noEarlyRoutes, hint: noEarlyRoutes ? 'nothing to do' - : `move the route${early.length === 1 ? '' : 's'} on line${early.length === 1 ? '' : 's'} ${early.join(', ')} below the guard, or move your body parser above them`, + : earlyRouteAdvice(early, entry ? spec.call(entry.appVar).trim() : ''), }, ] : []), diff --git a/tests/protect/adapters.test.ts b/tests/protect/adapters.test.ts index cef8a121..987f15cd 100644 --- a/tests/protect/adapters.test.ts +++ b/tests/protect/adapters.test.ts @@ -112,6 +112,14 @@ describe('Express adapter', () => { { label: 'express.urlencoded()', imports: "import express from 'express';", parser: 'app.use(express.urlencoded({ extended: true }));' }, { label: 'body-parser', imports: "import express from 'express';\nimport bodyParser from 'body-parser';", parser: 'app.use(bodyParser.json());' }, { label: 'a destructured json()', imports: "import express, { json } from 'express';", parser: 'app.use(json());' }, + { label: 'a path-scoped parser', imports: "import express from 'express';", parser: "app.use('/api', express.json());" }, + { label: 'a parser after other middleware', imports: "import express from 'express';\nimport cors from 'cors';", parser: 'app.use(cors(), express.json());' }, + { label: 'a parser followed by other middleware', imports: "import express from 'express';\nimport cors from 'cors';", parser: 'app.use(express.json(), cors());' }, + { + label: 'a multi-line call', + imports: "import express from 'express';", + parser: "app.use(\n '/api',\n express.json({ limit: '1mb', verify: (req, res, buf) => { req.raw = buf.toString(); } }),\n);", + }, ]; for (const { label, imports, parser } of parserVariants) { it(`wires after ${label} (not just express.json)`, () => { @@ -133,6 +141,39 @@ describe('Express adapter', () => { }); } + it('leaves a parser that shares its call with a router unwired, since the router would run first', () => { + const dir = tmp('ps-express-parser-router-'); + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ type: 'module', dependencies: { express: '^4.21.2' } })); + const original = "import express from 'express';\nimport router from './routes.js';\nconst app = express();\napp.use('/api', express.json(), router);\n"; + writeFileSync(path.join(dir, 'server.js'), original); + try { + runProtect(dir); + expect(read(dir, 'server.js')).toBe(original); + expect(runVerify(dir).wired).toBe(false); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); + + it('asks for the guard to go before middleware registered above it, not for the middleware to move only', () => { + const dir = tmp('ps-express-early-middleware-'); + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ type: 'module', dependencies: { express: '^4.21.2' } })); + writeFileSync( + path.join(dir, 'server.js'), + "import express from 'express';\nimport { securityHeaders } from './headers.js';\nconst app = express();\napp.use(securityHeaders);\napp.use(express.json());\napp.get('/', (req, res) => res.end());\n", + ); + try { + runProtect(dir); + const check = runVerify(dir).checks.find((c) => c.label.includes('every route registered after the guard')); + expect(check?.ok).toBe(false); + expect(check?.hint).toBe( + 'the guard must be registered before line 5: move `app.use(patchstackMiddleware);` and your body parser above it, or move it below the guard', + ); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); + it('scaffolds but does not claim full wiring when no JSON body parser is present', () => { const dir = tmp('ps-express-no-parser-'); writeFileSync(