Repository navigation
feat(node)!: normalize configuration casing and narrow event options - #5757
Conversation
PR overviewThe PR normalizes Node client configuration names to camelCase and narrows event options, including changing the event hook option from One compatibility issue remains open: legacy configuration names are silently ignored for JavaScript callers and TypeScript callers that bypass strict typing. Applications upgrading without renaming Open issues (1)
Fixed/addressed: 0 · PR risk: 4/10 Reviews |
|
|
✅ Security review complete — 1 finding posted as a review, in 6 min. Add the |
| // is not an error. | ||
| private _runBeforeSend(eventMessage: EventMessage, onError?: () => void): EventMessage | null { | ||
| const beforeSend = this.options.before_send | ||
| const beforeSend = this.options.beforeSend |
There was a problem hiding this comment.
Low: Legacy before_send silently ignored, so redaction hooks stop running
The client now reads only this.options.beforeSend, and the constructor (lines 496-519) just spreads options without checking for the old names. A JavaScript app, or a TypeScript app whose config is typed any or cast, that upgrades and still passes before_send gets no error and no warning. Its hook stops running, and events it used to drop or scrub go to PostHog unchanged. TypeScript catches this only for strictly typed callers. The same applies to disable_capture_url_hashes: the old name is silently ignored, so URL fragments are no longer stripped from captured request URLs.
The constructor already warns when POSTHOG_CAPTURE_MODE is set (warnIfCaptureModeSet). Doing the same here would surface the rename: if before_send, disable_capture_url_hashes, custom_blocked_useragents, or __preview_capture_bot_pageviews is present in options, call console.error, not the debug-only logger. Since before_send is the documented way to redact data, consider failing closed instead: disable the client, or map the old name to the new one for one major version, rather than sending events the app expects to be filtered.
Coherence📄 0 spec file errors · ⛔ 0 broken rules · 🚪 0 unchecked inputs · 🐛 0 bugs that came back What is Coherence?Coherence compares the code with its spec files ( This check read 44 parts of the code and 7 rules. Tip Nothing to fix. |
| // is not an error. | ||
| private _runBeforeSend(eventMessage: EventMessage, onError?: () => void): EventMessage | null { | ||
| const beforeSend = this.options.before_send | ||
| const beforeSend = this.options.beforeSend |
There was a problem hiding this comment.
The renamed before_send hook is silently ignored at runtime, so a 5.x-style redaction or drop hook fails open and every event is sent unfiltered
privacy (fail-open config; defence-in-depth) (confidence 4/5)
Details
PostHogBackendClient._runBeforeSend (packages/node/src/client.ts:4375) now reads only this.options.beforeSend. The constructor (client.ts:496-514) spreads the caller's options into this.options as given. Nothing in packages/node/src reads before_send, disable_capture_url_hashes, custom_blocked_useragents or __preview_capture_bot_pageviews any more, and nothing warns when one of them is passed. TypeScript rejects the old names only in a fresh object literal (src/__tests__/types/event-options.ts). A JavaScript caller, or a config that is spread or built elsewhere, still passes them and loses them without any message.
before_send is the SDK's documented control for redacting or dropping sensitive events, and this file treats it as one. A hook that throws fails closed and drops the event (client.ts:4393-4399). A hook passed under its 5.x name fails open: it never runs, and every event goes out unfiltered. In the same way, disable_capture_url_hashes: true is ignored, so express.ts:48, fetch-request.ts:113 and nestjs.ts:114 keep URL fragments in $current_url. That matters less on the server, where clients rarely send fragments.
This PR's own update missed two JavaScript consumers in this repo, and both show the failure:
compliance/node/adapter.mjs:219still setsbefore_sendon the workspace build.packages/nextjs-config/tests/integration/app/pages/api/release.js:7setsbefore_send(){ return null }next to afetchthat "must never send analytics requests".run.mjs:160packs the current workspaceposthog-node, so after this change that event is no longer dropped and reachesfetch.
Impact — A JS integrator upgrades to 6.x with new PostHog(key, { before_send: scrubPII }), a config shape still shown in the 5.x Node docs. The emails, tokens or whole events that the hook was removing are then sent to the PostHog project and stored there, and no warning appears. No attacker is needed. What still holds: the TypeScript literal check, and the major version bump with its migration guide. So this is a defence-in-depth gap, not a direct exposure path.
Fix — Detect the old names at construction, as warnIfCaptureModeSet() (client.ts:993) already does for a removed setting. For the privacy hook, consider failing closed:
const RENAMED_OPTIONS = {
before_send: 'beforeSend',
disable_capture_url_hashes: 'disableCaptureUrlHashes',
custom_blocked_useragents: 'customBlockedUserAgents',
__preview_capture_bot_pageviews: '__previewCaptureBotPageviews',
} as const
for (const [oldName, newName] of Object.entries(RENAMED_OPTIONS)) {
if (oldName in options) {
console.error(`[PostHog] \`${oldName}\` was renamed to \`${newName}\` in posthog-node 6 and is ignored.`)
}
}Also consider disabling the client, or throwing, when before_send is set and beforeSend is not, so a redaction hook is never skipped without notice. Separately, update the two in-repo fixtures above.
Agent-driven security review. Traced statically end to end. No runtime probe was run, because the sandbox has no built dist or installed dependencies.
Node SDK compliance v2Commit: 048af60 Capture v1 — acceptance✅ 289 passed / ❌ 8 non-passing / Drill-down: run artifacts → ❌ server_snapshot_payload_false — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_zero — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_null — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertionFlags field differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:135 the first flags request field "geoip_disable" should equal JSON false Operation: Field: Expected: false Actual value: true ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.dependency_error — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1174 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.error — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1213 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.error_with_value — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1252 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.v1_failed — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1425 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: Harness exit: 1; report validation exit: 1. Capture v1 — migration✅ 261 passed / ❌ 5 non-passing / Drill-down: run artifacts → ❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertionFlags field differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:135 the first flags request field "geoip_disable" should equal JSON false Operation: Field: Expected: false Actual value: true ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.dependency_error — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1174 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.error — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1213 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.error_with_value — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1252 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: ❌ migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature::Legacy getter reads reader fixture readers.v1_failed — failed_assertionGetter value differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v4-legacy-getter.feature:1425 the public flag getter should return exactly JSON false Operation: Arguments: {"key":"garden-layout","distinct_id":"flags-v4-person"}
Expected: false Actual outcome: Harness exit: 1; report validation exit: 1. |
SDK performance: posthog-node1 change worth reviewing: 1 observed regression. Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.
View all results
Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals. Each shard uses its own runner; compare Before PR against With PR within a row, not across shards. Compared 102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in |
A new stamphog review started for this PR — the fresh verdict replaces this approval.
There was a problem hiding this comment.
Not approved — this change needs a human reviewer.
Re-add the stamphog label to request another review once you have addressed this.
Both reviewers' privacy concerns remain unaddressed in the current code, and no current-head review covers the public API and privacy-sensitive changes. Address the client.ts findings, then request review from Eli Reisman, Vincent (Wen Yu) Ge, or another teammate before re-requesting.
- Author wrote 4% of the modified lines and has 92 merged PRs in these paths (familiarity MODERATE).
- @veria-ai on packages/node/src/client.ts: the constructor preserves caller options without translating or rejecting legacy keys, while _runBeforeSend reads only the renamed hook and returns the event unchanged when it is absent. Legacy JavaScript redaction/drop hooks therefore stop running; the request integrations likewise read only the renamed URL-fragment setting. Add runtime compatibility or fail-closed handling and regression tests before re-requesting.
- @posthog-security-review-bot on packages/node/src/client.ts: the older review's privacy concern remains present in the current code: legacy hook configuration can allow previously filtered events to be transmitted unchanged. Address that inline finding and obtain a fresh review before re-requesting.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✓ | no deny categories matched |
| every_file_attested | ✓ | not a bot PR |
| size | ✓ | 136L, 11F substantive, 728L/32F incl. docs/generated/snapshots — within ceiling |
| tier | ✓ | T1-agent / T1d-complex (728L, 32F, two-areas, feat) |
| stamphog 2.9.0 | .stamphog/policy.yml @ fbf9bff · reviewed head fbf9bff |
Problem
The Node 6 release is an opportunity to make SDK configuration consistently camelCase and catch invalid event-option values in TypeScript.
Changes
before_send→beforeSend,custom_blocked_useragents→customBlockedUserAgents,disable_capture_url_hashes→disableCaptureUrlHashes, and__preview_capture_bot_pageviews→__previewCaptureBotPageviews.EventOptionstype across event, exception, alias, context, registration, prepared-event, and hook APIs: explicit boolean fields for known options, with JSDoc and a string index signature for additional JSON-valued options.Targets
capture-v1(#5407); these are breaking API changes for the upcoming Node 6 major release. Includes a major changeset. The affected capture/before-send behavior remains unchanged relative to the release branch.Validation
git diff --check.Release info
🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Implemented with Pi and independently inspected by a fresh read-only reviewer. Human review is required before merge.