Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions AGENT-INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
20 changes: 18 additions & 2 deletions src/protect/install/adapters/express.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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\(\)/,
Expand All @@ -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 = {
Expand Down
48 changes: 33 additions & 15 deletions src/protect/install/register.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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 };
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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())}.`,
);
}
}
Expand Down Expand Up @@ -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 {
Expand All @@ -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
Expand Down Expand Up @@ -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() : ''),
},
]
: []),
Expand Down
41 changes: 41 additions & 0 deletions tests/protect/adapters.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)`, () => {
Expand All @@ -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(
Expand Down