@bernierllc/sentry-policy
v0.2.1
Published
Shared Sentry SDK policy for Bernier LLC apps: privacy-safe init options, environment/release resolution, a pure beforeSend scrubber, and cross-language scrubber test vectors.
Readme
@bernierllc/sentry-policy
Shared Sentry SDK policy for BernierLLC apps: sample rates, the privacy baseline (dataCollection), replay off, ignoreErrors, environment/release resolution, and a pure beforeSend scrubber. It also ships the scrubber's test vectors as JSON, so non-JS apps (PrevostList's Python before_send) are held to the same rules.
It returns options, not a client. Every app calls Sentry.init itself with its own SDK, DSN and integrations. There is no wrapper around Sentry.init and no runtime dependency on any Sentry SDK.
Install
npm install @bernierllc/sentry-policy
# plus the SDK for your runtime, version 10.57.0 or later (v11 recommended)
npm install @sentry/node # or @sentry/browser, @sentry/react, @sentry/nextjs@sentry/* 10.57.0 or later is required. See Why dataCollection, not sendDefaultPii.
Environment variables
The package reads exactly two variables, and only from the object you pass to sentryPolicy(env). It never reads process.env itself (browsers have none):
| Variable | Read by | Meaning |
|---|---|---|
| SENTRY_ENVIRONMENT | this package | production or staging. Unset or empty means development. Any other value throws SentryPolicyError (INVALID_SENTRY_ENVIRONMENT), because a typo like prod would otherwise file production errors under development with tracing off. |
| RAILWAY_GIT_COMMIT_SHA | this package | Becomes release. Unset means release is omitted. Railway sets it on every deploy. |
The rest are read by the app, not this package:
| Variable | Where | Meaning |
|---|---|---|
| SENTRY_DSN | Node / server runtimes | DSN passed to Sentry.init. |
| NEXT_PUBLIC_SENTRY_DSN | Next.js browser bundle | DSN for the client runtime (inlined at build time). |
| VITE_SENTRY_DSN | a10d Vite browser bundle | DSN for the browser (inlined at build time). Pair it with VITE_SENTRY_ENVIRONMENT. |
| SENTRY_AUTH_TOKEN | CI only | Source-map upload. Never shipped to a runtime. |
| SENTRY_ORG | CI only | bernier-llc. |
| SENTRY_PROJECT | CI only | The app's Sentry project slug. |
A missing DSN in production is the app's boot check to report: fail the boot, don't silently start without Sentry. This package never disables Sentry.
What sentryPolicy(env) returns
| Option | Value |
|---|---|
| environment | from SENTRY_ENVIRONMENT (above) |
| release | RAILWAY_GIT_COMMIT_SHA, omitted when unset |
| dataCollection | the privacy baseline (below) |
| sampleRate | 1.0 (every error) |
| tracesSampleRate | production 0.1, staging and development 0 |
| replaysSessionSampleRate / replaysOnErrorSampleRate | 0 (replay off) |
| ignoreErrors | a fresh copy of SENTRY_IGNORE_ERRORS |
| beforeSend / beforeSendTransaction | scrubSentryEvent |
Every call returns fresh arrays and objects, so an app can append to ignoreErrors without affecting other callers.
Usage
Node (Express, workers, MCP servers)
// instrument.ts: import this before anything else
import * as Sentry from '@sentry/node';
import { sentryPolicy } from '@bernierllc/sentry-policy';
if (!process.env.SENTRY_DSN && process.env.SENTRY_ENVIRONMENT === 'production') {
throw new Error('SENTRY_DSN is required in production');
}
Sentry.init({
dsn: process.env.SENTRY_DSN,
...sentryPolicy(process.env),
});a10d (Vite, browser)
Vite only exposes VITE_-prefixed variables, so map them onto the names the package reads:
import * as Sentry from '@sentry/browser'; // or @sentry/react
import { sentryPolicy } from '@bernierllc/sentry-policy';
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN,
...sentryPolicy({
SENTRY_ENVIRONMENT: import.meta.env.VITE_SENTRY_ENVIRONMENT,
RAILWAY_GIT_COMMIT_SHA: import.meta.env.VITE_RAILWAY_GIT_COMMIT_SHA,
}),
});VITE_RAILWAY_GIT_COMMIT_SHA must be set at build time (for example VITE_RAILWAY_GIT_COMMIT_SHA=$RAILWAY_GIT_COMMIT_SHA vite build) so browser events carry the same release as the server.
Next.js
// instrumentation.ts
import * as Sentry from '@sentry/nextjs';
import { sentryPolicy } from '@bernierllc/sentry-policy';
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs' || process.env.NEXT_RUNTIME === 'edge') {
Sentry.init({ dsn: process.env.SENTRY_DSN, ...sentryPolicy(process.env) });
}
}
export const onRequestError = Sentry.captureRequestError;// instrumentation-client.ts
import * as Sentry from '@sentry/nextjs';
import { sentryPolicy } from '@bernierllc/sentry-policy';
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
...sentryPolicy({
SENTRY_ENVIRONMENT: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT,
RAILWAY_GIT_COMMIT_SHA: process.env.NEXT_PUBLIC_RAILWAY_GIT_COMMIT_SHA,
}),
});Adding your own beforeSend
Run the scrubber last, so nothing your hook adds escapes it:
import { scrubSentryEvent, sentryPolicy } from '@bernierllc/sentry-policy';
Sentry.init({
dsn: process.env.SENTRY_DSN,
...sentryPolicy(process.env),
beforeSend(event) {
if (isExpectedBusinessError(event)) return null;
return scrubSentryEvent(event);
},
});Why dataCollection, not sendDefaultPii
Sentry JS SDK v11 removed sendDefaultPii. Its replacement, dataCollection (added in 10.57.0), collects everything when left unset: user info, cookies, request headers and bodies, query params, GraphQL documents, gen-AI and MCP inputs/outputs, and DB query data. Passing sendDefaultPii: false to v11 is silently ignored, so it leaves all of that on.
sentryDataCollection() (included in sentryPolicy) returns Sentry's documented "keep the v10 defaults" baseline from the v10 → v11 migration guide, plus two tightenings:
userInfo,cookies,databaseQueryData,genAI,graphQLoff;httpBodies: [].- Identity headers and query params denied (
forwarded,-ip,remote-,via,-user). - Added:
mcpinputs/outputs,queues(task arguments) andstackFrameVariables(local variable values) off. Both of the last two default on in v11 and hold raw values the scrubber cannot recognize. - Added:
SENTRY_SENSITIVE_HEADERS(authorization,cookie,set-cookie,x-api-key, …) in both header deny lists, so auth headers are dropped when collected as well as inbeforeSend.
The scrubber
scrubSentryEvent(event) is pure: it returns a new event and never mutates its input. On every event and transaction it:
- Deletes
request.data(bodies), everycookieskey anywhere, anduser.email/user.ip_address/user.username(user.idstays). - Drops
SENTRY_SENSITIVE_HEADERS(case-insensitive) from everyheadersobject. - Redacts every remaining string value with
redactSentryText, in this order:
| Matches | Becomes |
|---|---|
| Bearer <token> (bearer/BEARER too), token of 16+ characters | Bearer [redacted-token], keyword spelling kept |
| JWTs (eyJ….….…) | [redacted-token] |
| SendGrid SG.…, Stripe sk_/rk_/pk_ live/test, whsec_… | [redacted-token] |
| postgres://…, postgresql://… | [redacted-connection-string] |
| credentials in any other URL (redis://user:pass@host) | redis://[redacted-credentials]@host |
| email addresses, including percent-encoded ones in query strings (jane%40example.com) | [redacted-email] |
Circular references become '[Circular]'. Stack frames, transaction names, span descriptions and trace ids are left unchanged unless they contain one of the shapes above.
Not covered here: object keys are never redacted, and secrets that are identifiable only by their key name (extra.password: "hunter2") are left to Sentry's server-side data scrubbing, the second layer. Keep "Data Scrubber" and "Use Default Scrubbers" enabled in each Sentry project's Security & Privacy settings. Also not covered yet: opaque tokens in query strings (?token=abc123… that is not a JWT) and the api_/mcp_ key prefixes. Server-side scrubbing is the backstop for these.
Porting the rules to Python: the regexes use syntax shared by JS and Python re. The only change is the replacement backreference: JS $1 becomes Python \1.
Scrubber vectors (cross-language contract)
fixtures/scrubber-vectors.json holds { version, vectors: [{ name, input, expected }] }. This package's tests assert scrubSentryEvent(input) deep-equals expected for every vector. Any other implementation of the rules must pass the same file.
From JS:
import vectors from '@bernierllc/sentry-policy/fixtures/scrubber-vectors.json' with { type: 'json' };From Python (PrevostList), take the file from the pinned npm tarball so both languages test against the same version:
npm pack @bernierllc/[email protected]
tar -xzf bernierllc-sentry-policy-0.1.0.tgz package/fixtures/scrubber-vectors.json
mv package/fixtures/scrubber-vectors.json tests/fixtures/# tests/test_sentry_before_send.py
import json
from pathlib import Path
import pytest
from app.sentry import before_send
VECTORS = json.loads(
(Path(__file__).parent / "fixtures" / "scrubber-vectors.json").read_text()
)["vectors"]
@pytest.mark.parametrize("v", VECTORS, ids=[v["name"] for v in VECTORS])
def test_before_send_matches_shared_vectors(v):
assert before_send(v["input"], None) == v["expected"]The Python SDK still uses send_default_pii=False (the dataCollection change is JS-only), so Python apps set that and use this before_send.
API
| Export | Kind |
|---|---|
| sentryPolicy(env) | all options above |
| sentryDataCollection() | the dataCollection baseline |
| resolveSentryEnvironment(env), resolveSentryRelease(env), tracesSampleRateFor(environment) | the individual rules |
| scrubSentryEvent(event), redactSentryText(text) | the scrubber and its string rules |
| SENTRY_IGNORE_ERRORS, SENTRY_SENSITIVE_HEADERS, SENTRY_ENVIRONMENTS | constants |
| SentryPolicyError | thrown for an invalid SENTRY_ENVIRONMENT (code: 'INVALID_SENTRY_ENVIRONMENT') |
| SentryPolicyEnv, SentryPolicyOptions, SentryDataCollection, SentryEnvironment | types |
License
Limited-use license. See LICENSE.
