diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e4a9bcda..ed609668 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -403,6 +403,26 @@ jobs: - name: Install and check the real TanStack framework contract run: node scripts/tanstack-consumer.mjs --tarball packed/*.tgz + fastify-startup: + name: Fastify startup from the packed artifact + needs: pack + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 22.x + - uses: actions/download-artifact@v8 + with: + name: packed-tarball + path: packed + - name: Start and screen unmodified Fastify apps + run: | + set -euo pipefail + node scripts/framework-consumers.mjs fastify-startup-esm packed/*.tgz + node scripts/framework-consumers.mjs fastify-startup-cjs packed/*.tgz + next-consumers: name: Next.js ${{ matrix.next }} (${{ matrix.bundler }}) production integration needs: pack @@ -453,6 +473,7 @@ jobs: - production-audit - next-consumers - tanstack-consumer + - fastify-startup runs-on: ubuntu-latest steps: diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md index 1d63f001..c3ba057d 100644 --- a/AGENT-INSTALL.md +++ b/AGENT-INSTALL.md @@ -8,7 +8,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s - **Source and releases:** MIT-licensed, source at https://github.com/patchstack/connect. Each version is published to npm from that repository's GitHub Actions workflow with an npm provenance attestation. - **How to check it yourself:** `npm view @patchstack/connect` shows the live registry metadata, including the repository and the attestation. After installing, `npm audit signatures` verifies the registry signatures and provenance attestations of the installed packages, this one included. - **What it does:** it sends the project's package names and versions to Patchstack for vulnerability matching, adds the Patchstack Connector widget to the site when asked (`setup --widget`, or `widget`), installs a runtime exploit guard (`protect`) in the server's request path, and adds scan steps to the install and build scripts. `setup` and the `prebuild` hook also upload a structural map of the server (routes, input names, the packages behind each sink, file:line) so protection rules can target the app's own parameters — never source text or environment values. Run on its own, `map` sends nothing unless you pass `--upload`. The [Command reference](#command-reference) lists every command, what it reads and writes, and what it sends. -- **Host-managed Node applications:** The optional `@patchstack/connect/register` preload starts the existing live guard for a site configured by the host. It can enable outbound screening. The host can mount its Express adapter for request and response screening. The optional `prepare-deploy` command uploads the dependency manifest and structural input map for an existing site and writes a credential-free deployment metadata file for the preload. See the [host-managed Node setup](README.md#host-managed-node-applications). +- **Host-managed Node applications:** The optional `@patchstack/connect/register` preload starts the existing live guard for a site configured by the host. It can enable outbound screening. The host can mount its Express adapter for request and response screening. The `@patchstack/connect/register/fastify` pilot attaches the Fastify 5.12.1 adapter at startup without editing the app. The optional `prepare-deploy` command uploads the dependency manifest and structural input map for an existing site and writes a credential-free deployment metadata file for the preload. See the [host-managed Node setup](README.md#host-managed-node-applications). - **How setup ends:** run outside a terminal, as you run it, `setup` ends with `──── Summary ────` and a short message written for the person: what Patchstack found, the link to connect the site, what is left to do and the next step. **That summary is your final message.** Show it exactly as written, with every section. It ends by telling the person to say "done" once they have done the one thing it asks — usually connecting their account. When they say "done", run `npx @patchstack/connect next`, which checks where the project stands and says the next thing to do; show what it prints the same way. Do not add a list of the files `setup` changed: the setup output lists them, so answer from it if the person asks. Do not reword it, drop a section, or add your own: no recap, no account of the commands you ran. Add at most one line, after it, for something you did beyond `setup`. If the summary did not reach you (long output can be cut short), run `npx @patchstack/connect summary`: it prints the same summary again, from `.patchstack/summary.md`, where `setup` saves it. "The message you end on" below has the details, and "Commands for later" lists what to run when the person asks for more (`vulns` shows the vulnerabilities). ## Choose the project path first diff --git a/README.md b/README.md index 9f6ac1ee..8c58acba 100644 --- a/README.md +++ b/README.md @@ -557,6 +557,21 @@ the app already needs. The ESM preload and the middleware import use the same guard instance. CommonJS apps can load the same export with `await import()` during their async startup. +The Fastify startup pilot attaches the existing adapter without editing the app +source or copying a plugin file. On a Node runtime with synchronous module +hooks and `require(esm)`, start a Fastify 5.12.1 app that imports one installed +copy of Fastify by package name with: + +```sh +node --import @patchstack/connect/register/fastify server.js +``` + +Use the same site environment as the base preload. The pilot supports +unbundled ESM and CommonJS entry points. For other Fastify versions, bundled +apps, or app entries that load Fastify before the hook, use the framework's +plugin integration. Activate either the preload adapter or the in-app adapter +once per app. + To bind the guard to the map for a deployment, run this from the app's source directory with the site UUID and API key set. Set `PATCHSTACK_ENVIRONMENT` to `production` or `sandbox` for the deployment tier. Use an existing, separate @@ -574,7 +589,9 @@ succeed. The preload refuses an incomplete file or one for a different site. It reports the manifest checksum with live status and presents the map identity when fetching rules. Patchstack still needs to confirm the map before scoped rules can block. A rollback should start the older artifact with its original -metadata. If that map is no longer confirmed, its scoped rules only detect. +metadata. The rules service selects rules for the build presented, and the +guard only enforces a scoped rule when its build is confirmed. A scoped rule +that arrives without confirmation can only detect. Serialize deployments for the same site to keep the latest reported map aligned with the build you activate. For a custom Patchstack service, configure `PATCHSTACK_ENDPOINT` for the build and the corresponding diff --git a/field-test/hosted-startup.md b/field-test/hosted-startup.md index 089a46d2..543c74fd 100644 --- a/field-test/hosted-startup.md +++ b/field-test/hosted-startup.md @@ -20,7 +20,9 @@ byte-for-byte identical, parsed JSON still reaches the app, a matching request is blocked, scoped response rules redact values, and a stream's first chunk reaches the client while the response is still open. The tests ran on Node 22.22, 24.21 and 26.8. The hook runs via an explicit `node --import` argument, -so the host can leave `NODE_OPTIONS` untouched. +so the host can leave `NODE_OPTIONS` untouched. The live fixture starts the +package's `@patchstack/connect/register/fastify` export, then runs the separate +test probe. A deployed app only needs the package preload. For a partner pilot, start with one app per process and add the hook through the service manager or container command. Verify the framework and package diff --git a/package.json b/package.json index 9930042e..1bb62f18 100644 --- a/package.json +++ b/package.json @@ -43,6 +43,9 @@ "default": "./dist/register.js" } }, + "./register/fastify": { + "import": "./dist/hosted/register-fastify.mjs" + }, "./protect": { "workerd": "./dist/protect.edge.js", "worker": "./dist/protect.edge.js", diff --git a/scripts/copy-protect-templates.mjs b/scripts/copy-protect-templates.mjs index cc7714e2..4f817179 100644 --- a/scripts/copy-protect-templates.mjs +++ b/scripts/copy-protect-templates.mjs @@ -25,3 +25,6 @@ console.log('copied protect types -> dist/protect.d.ts, dist/protect.d.cts'); mkdirSync('dist/protect/runtime', { recursive: true }); copyFileSync('src/protect/install/runtime/report-listeners.cjs', 'dist/protect/runtime/report-listeners.cjs'); console.log('copied listener reporter -> dist/protect/runtime/report-listeners.cjs'); + +// Keep the loader and its ESM facade as separate files for Node resolution. +cpSync('src/hosted', 'dist/hosted', { recursive: true }); diff --git a/scripts/fastify-startup-live.mjs b/scripts/fastify-startup-live.mjs index fb3e518e..b455267d 100644 --- a/scripts/fastify-startup-live.mjs +++ b/scripts/fastify-startup-live.mjs @@ -1,6 +1,5 @@ import assert from 'node:assert/strict'; import { readFileSync } from 'node:fs'; -import { installFastifyHook } from './preload.mjs'; assert.equal(process.env.PS_FASTIFY_LIVE, '1'); assert.equal(process.platform, 'linux'); @@ -43,4 +42,3 @@ console.log('Fastify live pilot ' + JSON.stringify({ matched: status.matched, mapRules: status.mapRules, delivered: bundle.firewall.length, scoped: status.rules.scoped, scopedBlocking: status.rules.scopedBlocking, })); -installFastifyHook(protection); diff --git a/scripts/fastify-startup-preload.mjs b/scripts/fastify-startup-preload.mjs deleted file mode 100644 index 3f616879..00000000 --- a/scripts/fastify-startup-preload.mjs +++ /dev/null @@ -1,40 +0,0 @@ -// Proof of concept for one host-managed Fastify app per Node process. -import { createRequire, registerHooks } from 'node:module'; -import { pathToFileURL } from 'node:url'; -import { patchstackFastify } from './fastify-guard.mjs'; - -const entry = process.argv[1]; -if (!entry) throw new Error('The Fastify startup fixture needs an application entry file.'); - -const requireFromEntry = createRequire(entry); -const factoryPath = requireFromEntry.resolve('fastify'); -if (requireFromEntry.cache[factoryPath]) throw new Error('The Fastify startup fixture must load before Fastify.'); -const { version } = requireFromEntry('fastify/package.json'); -if (version !== '5.12.1') throw new Error('The Fastify startup fixture needs Fastify 5.12.1.'); - -const fastify = requireFromEntry(factoryPath); -const factoryUrl = pathToFileURL(factoryPath).href; -const facadeUrl = new URL('./facade.mjs', import.meta.url).href; - -let protection; - -export function createGuardedApp(...options) { - return fastify(...options).register(patchstackFastify, { protection }); -} -Object.assign(createGuardedApp, fastify); -createGuardedApp.fastify = createGuardedApp; -createGuardedApp.default = createGuardedApp; - -export function installFastifyHook(liveProtection) { - protection = liveProtection; - registerHooks({ - resolve(specifier, context, nextResolve) { - const resolved = nextResolve(specifier, context); - if (specifier !== 'fastify') return resolved; - if (resolved.url !== factoryUrl) throw new Error('The Fastify startup fixture only covers one installed copy.'); - return { url: facadeUrl, format: 'module', shortCircuit: true }; - }, - }); -} - -if (process.env.PS_FASTIFY_LIVE !== '1') installFastifyHook(); diff --git a/scripts/framework-consumers.mjs b/scripts/framework-consumers.mjs index ed2db801..1f9c8bef 100644 --- a/scripts/framework-consumers.mjs +++ b/scripts/framework-consumers.mjs @@ -1,6 +1,7 @@ import assert from 'node:assert/strict'; import { spawn, spawnSync } from 'node:child_process'; import { once } from 'node:events'; +import { createServer as createHttpServer } from 'node:http'; import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; import { createServer } from 'node:net'; import { tmpdir } from 'node:os'; @@ -181,8 +182,7 @@ fixtures.fastify = fastifyFixture('cjs'); for (const format of ['esm', 'cjs']) { fixtures['fastify-startup-' + format] = { ...fastifyFixture(format), - rules: 'host/rules.json', - preload: './host/preload.mjs', + preload: true, }; } @@ -221,6 +221,9 @@ function run(command, args, childEnv = env) { const child = spawnSync(command, args, { cwd, env: childEnv, encoding: 'utf8', timeout: 180_000 }); assert.equal(child.status, 0, [child.error?.message, child.stdout, child.stderr].join('\n').replaceAll(cwd, '')); } +const fixtureSite = '11111111-1111-4111-8111-111111111111'; +let localRulesUrl; + async function check(protectedApp, liveBuild) { const listener = createServer().listen(0, '127.0.0.1'); await once(listener, 'listening'); @@ -240,9 +243,16 @@ async function check(protectedApp, liveBuild) { PS_FASTIFY_SCOPE_EXPECT: liveBuild.scopedOutcome, } : {}), }); + } else if (protectedApp && localRulesUrl) { + Object.assign(processEnv, { + PATCHSTACK_SITE_UUID: fixtureSite, + PATCHSTACK_API_KEY: 'synthetic-key-1', + PATCHSTACK_PULSE_RULES_URL: localRulesUrl, + PATCHSTACK_MODE: 'block', + }); } - const preload = liveBuild ? './host/live.mjs' : fixture.preload; - const flags = protectedApp && preload ? ['--import', preload] : []; + const flags = protectedApp && fixture.preload ? ['--import', '@patchstack/connect/register/fastify'] : []; + if (liveBuild) flags.push('--import', './host/live.mjs'); const app = spawn(process.execPath, [...flags, ...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; }); @@ -332,6 +342,7 @@ async function check(protectedApp, liveBuild) { } } } +let mockRules; try { put('package.json', JSON.stringify({ name: 'framework-fixture', private: true, type: 'module', dependencies: { ...fixture.dependencies, '@patchstack/connect': `file:${resolve(tarball)}` } })); @@ -341,32 +352,43 @@ try { await check(false); const packageDir = 'node_modules/@patchstack/connect'; if (fixture.preload) { - mkdirSync(join(cwd, 'host'), { recursive: true }); - copyFileSync(fileURLToPath(new URL('./fastify-startup-preload.mjs', import.meta.url)), join(cwd, fixture.preload)); if (live) { + mkdirSync(join(cwd, 'host'), { recursive: true }); copyFileSync(fileURLToPath(new URL('./fastify-startup-live.mjs', import.meta.url)), join(cwd, 'host/live.mjs')); } - put('host/facade.mjs', `import { createGuardedApp } from './preload.mjs'; -export { createGuardedApp as fastify, createGuardedApp as default, createGuardedApp as 'module.exports' }; -export const { errorCodes, LogController } = createGuardedApp;`); - copyFileSync(join(cwd, packageDir, 'dist/protect/templates/fastify-plugin.js'), join(cwd, 'host/fastify-guard.mjs')); } else { const cli = join(packageDir, '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: [ + const fixtureBundle = 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: {} })); + ], whitelists: [], whitelist_keys: {} }); + if (fixture.preload && !live) { + mockRules = createHttpServer((incoming, reply) => { + incoming.resume(); + if (incoming.method === 'POST' && incoming.url === '/monitor/pulse/token') { + reply.writeHead(200, { 'content-type': 'application/json' }).end('{"access_token":"synthetic-token"}'); + } else if (incoming.method === 'GET' && incoming.url === `/monitor/pulse/rules/${fixtureSite}` + && incoming.headers.authorization === 'Bearer synthetic-token') { + reply.writeHead(200, { 'content-type': 'application/json' }).end(fixtureBundle); + } else { + reply.writeHead(404).end(); + } + }); + mockRules.listen(0, '127.0.0.1'); + await once(mockRules, 'listening'); + localRulesUrl = `http://127.0.0.1:${mockRules.address().port}/monitor/pulse`; + } else if (!fixture.preload) { + put(fixture.rules, fixtureBundle); + } if (fixture.build) run(process.execPath, fixture.build); if (live) { - // A separate local bundle would make a broken live policy look healthy. - put(fixture.rules, JSON.stringify({ firewall: [], whitelists: [], whitelist_keys: {} })); const deployment = 'host/deployment.json'; run(process.execPath, [join(packageDir, 'dist/cli.js'), 'prepare-deploy', '--out', deployment], { ...env, PATCHSTACK_SITE_UUID: siteUuid, PATCHSTACK_API_KEY: apiKey, PATCHSTACK_ENVIRONMENT: 'sandbox', @@ -390,5 +412,7 @@ export const { errorCodes, LogController } = createGuardedApp;`); if (live) console.log(`PASS ${name}: Linux live-rule and build-identity checks with unchanged application source`); else console.log(`PASS ${name}: HTTP request screening, normal body parsing and response redaction${fixture.stream ? ' including stream headers' : ''}`); } finally { + mockRules?.close(); + mockRules?.closeAllConnections(); rmSync(cwd, { recursive: true, force: true }); } diff --git a/src/hosted/fastify-facade.mjs b/src/hosted/fastify-facade.mjs new file mode 100644 index 00000000..31d67efd --- /dev/null +++ b/src/hosted/fastify-facade.mjs @@ -0,0 +1,4 @@ +import { guardedFactory } from './fastify-hook.mjs'; + +export { guardedFactory as fastify, guardedFactory as default, guardedFactory as 'module.exports' }; +export const { errorCodes, LogController } = guardedFactory; diff --git a/src/hosted/fastify-hook.mjs b/src/hosted/fastify-hook.mjs new file mode 100644 index 00000000..9eee79c4 --- /dev/null +++ b/src/hosted/fastify-hook.mjs @@ -0,0 +1,42 @@ +import * as nodeModule from 'node:module'; +import { pathToFileURL } from 'node:url'; +import { patchstackFastify } from '../protect/templates/fastify-plugin.js'; + +export function installFastifyHook(protection) { + if (typeof nodeModule.registerHooks !== 'function' || !process.features.require_module) { + throw new Error('The Patchstack Fastify preload needs Node module hooks and require(esm).'); + } + const entry = process.argv[1]; + if (!entry) throw new Error('The Patchstack Fastify preload needs an application entry file.'); + + const requireFromEntry = nodeModule.createRequire(entry); + const factoryPath = requireFromEntry.resolve('fastify'); + if (requireFromEntry.cache[factoryPath]) { + throw new Error('The Patchstack Fastify preload must run before Fastify is loaded.'); + } + const { version } = requireFromEntry('fastify/package.json'); + if (version !== '5.12.1') throw new Error('The Patchstack Fastify pilot supports Fastify 5.12.1.'); + + const factory = requireFromEntry(factoryPath); + guardedFactory = Object.assign( + (...options) => factory(...options).register(patchstackFastify, { protection }), + factory, + ); + guardedFactory.fastify = guardedFactory; + guardedFactory.default = guardedFactory; + + const factoryUrl = pathToFileURL(factoryPath).href; + const facadeUrl = new URL('./fastify-facade.mjs', import.meta.url).href; + nodeModule.registerHooks({ + resolve(specifier, context, nextResolve) { + const resolved = nextResolve(specifier, context); + if (specifier !== 'fastify') return resolved; + if (resolved.url !== factoryUrl) { + throw new Error('The Patchstack Fastify pilot supports one installed Fastify copy per app.'); + } + return { url: facadeUrl, format: 'module', shortCircuit: true }; + }, + }); +} + +export let guardedFactory; diff --git a/src/hosted/register-fastify.mjs b/src/hosted/register-fastify.mjs new file mode 100644 index 00000000..51985d59 --- /dev/null +++ b/src/hosted/register-fastify.mjs @@ -0,0 +1,4 @@ +import { installFastifyHook } from './fastify-hook.mjs'; +import { protection } from '@patchstack/connect/register'; + +installFastifyHook(protection);