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
21 changes: 21 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -453,6 +473,7 @@ jobs:
- production-audit
- next-consumers
- tanstack-consumer
- fastify-startup
runs-on: ubuntu-latest

steps:
Expand Down
2 changes: 1 addition & 1 deletion AGENT-INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 18 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
4 changes: 3 additions & 1 deletion field-test/hosted-startup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
3 changes: 3 additions & 0 deletions scripts/copy-protect-templates.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 });
2 changes: 0 additions & 2 deletions scripts/fastify-startup-live.mjs
Original file line number Diff line number Diff line change
@@ -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');
Expand Down Expand Up @@ -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);
40 changes: 0 additions & 40 deletions scripts/fastify-startup-preload.mjs

This file was deleted.

52 changes: 38 additions & 14 deletions scripts/framework-consumers.mjs
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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,
};
}

Expand Down Expand Up @@ -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, '<fixture>'));
}
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');
Expand All @@ -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; });
Expand Down Expand Up @@ -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)}` } }));
Expand All @@ -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',
Expand All @@ -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 });
}
4 changes: 4 additions & 0 deletions src/hosted/fastify-facade.mjs
Original file line number Diff line number Diff line change
@@ -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;
42 changes: 42 additions & 0 deletions src/hosted/fastify-hook.mjs
Original file line number Diff line number Diff line change
@@ -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;
4 changes: 4 additions & 0 deletions src/hosted/register-fastify.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
import { installFastifyHook } from './fastify-hook.mjs';
import { protection } from '@patchstack/connect/register';

installFastifyHook(protection);
Loading