@flareapp/node 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -0,0 +1,834 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let _flareapp_core = require("@flareapp/core");
+let node_os = require("node:os");
+node_os = __toESM(node_os);
+let node_async_hooks = require("node:async_hooks");
+let node_fs_promises = require("node:fs/promises");
+let node_url = require("node:url");
+
+//#region src/context/body.ts
+/**
+* Content types accepted by default for body capture. JSON and
+* URL-encoded forms cover the vast majority of API payloads while keeping
+* the parser surface tiny. `\b` after the second alternative prevents
+* accidental matches like `application/x-www-form-urlencoded-foo` (artificial
+* but cheap to defend against). The leading `^` plus `\b` lets us match
+* either bare types or types with `; charset=utf-8` style suffixes.
+*/
+const DEFAULT_BODY_CONTENT_TYPES = /^application\/(json|x-www-form-urlencoded)\b/i;
+/**
+* Keys whose values get replaced with `[redacted]` during body redaction.
+* Reuses core's URL denylist so credentials, tokens, etc are caught with the
+* same regex everywhere (less surface for users to keep in sync).
+*/
+const DEFAULT_BODY_KEY_DENYLIST = _flareapp_core.DEFAULT_URL_DENYLIST;
+/**
+* Normalize, redact, serialize, and size-cap a request body for inclusion in
+* a Flare report.
+*
+* Accepts four runtime shapes (whatever the user hands us via
+* `runWithContext({ body, ... })`):
+*
+* - `string` — assumed to match the declared `contentType`. Must be JSON or
+*   form-encoded text per `bodyAllowedContentTypes`; otherwise dropped.
+* - `Buffer` — decoded as UTF-8 then treated like a string.
+* - `URLSearchParams` — flattened to a plain `Record<string, string>`. No
+*   content-type gate (the type is unambiguous from the shape).
+* - Other `object` (POJO, array) — used as-is, no content-type gate. This is
+*   the common middleware path (Express's `req.body`, Fastify's, etc).
+*
+* Anything else (`number`, `boolean`, class instance, stream) returns `null`
+* and the body is not reported.
+*
+* After parsing:
+*
+* 1. **Redact.** Walk the value, replacing any property whose key matches
+*    `bodyKeyDenylist` with `'[redacted]'`. Handles arrays, nested objects,
+*    and circular references (`WeakSet`-tracked, emits `'[Circular]'` on
+*    repeat sight).
+* 2. **Stringify.** `JSON.stringify`; if it throws (BigInt, Symbol, etc),
+*    drop the body entirely.
+* 3. **Truncate.** Cap at `bodyMaxBytes` UTF-8 bytes (the option's named
+*    semantic) INCLUDING the suffix. Truncation respects codepoint boundaries
+*    so the result decodes cleanly with no replacement characters.
+*
+* Returns the final JSON string, or `null` when the body should not be
+* reported (unknown shape, content-type miss, serialization failure).
+*/
+function captureBody(body, contentType, opts) {
+	if (body === void 0 || body === null) return null;
+	let parsed;
+	if (typeof body === "string") {
+		if (!matchesContentType(contentType, opts.bodyAllowedContentTypes)) return null;
+		parsed = parseString(body, contentType);
+		if (parsed === void 0) return null;
+	} else if (Buffer.isBuffer(body)) {
+		if (!matchesContentType(contentType, opts.bodyAllowedContentTypes)) return null;
+		parsed = parseString(body.toString("utf8"), contentType);
+		if (parsed === void 0) return null;
+	} else if (body instanceof URLSearchParams) parsed = Object.fromEntries(body.entries());
+	else if (Array.isArray(body) || isPlainObject(body)) parsed = body;
+	else return null;
+	const redacted = redact(parsed, opts.bodyKeyDenylist);
+	let serialized;
+	try {
+		serialized = JSON.stringify(redacted);
+	} catch {
+		return null;
+	}
+	return truncateToByteLimit(serialized, opts.bodyMaxBytes);
+}
+const TRUNCATION_SUFFIX = "…[truncated]";
+const TRUNCATION_SUFFIX_BYTES = Buffer.byteLength(TRUNCATION_SUFFIX, "utf8");
+/**
+* Truncate a serialized string so the resulting UTF-8 byte length never
+* exceeds `maxBytes`, including the appended truncation suffix.
+*
+* Walks backwards from the budget index while the byte at that position is a
+* UTF-8 continuation byte (`10xxxxxx`), stopping at the first byte that
+* starts a new codepoint. Slicing at that index leaves a buffer that decodes
+* cleanly with no replacement characters.
+*/
+function truncateToByteLimit(serialized, maxBytes) {
+	const buf = Buffer.from(serialized, "utf8");
+	if (buf.length <= maxBytes) return serialized;
+	if (maxBytes <= TRUNCATION_SUFFIX_BYTES) {
+		const suffixBuf = Buffer.from(TRUNCATION_SUFFIX, "utf8");
+		let cut = maxBytes;
+		while (cut > 0 && (suffixBuf[cut] & 192) === 128) cut--;
+		return suffixBuf.subarray(0, cut).toString("utf8");
+	}
+	let cut = maxBytes - TRUNCATION_SUFFIX_BYTES;
+	while (cut > 0 && (buf[cut] & 192) === 128) cut--;
+	return buf.subarray(0, cut).toString("utf8") + TRUNCATION_SUFFIX;
+}
+/**
+* Check whether a `content-type` header is on the allowlist. Normalizes to the
+* bare media type first: strips any parameters (`; charset=utf-8`), trims, and
+* lowercases, so the regex is tested against `application/json` rather than the
+* full header. This lets a strict custom regex like `/^application\/json$/`
+* still match `application/json; charset=utf-8`. Empty/missing is a hard miss.
+*/
+function matchesContentType(ct, allowed) {
+	if (!ct) return false;
+	const mediaType = ct.split(";")[0].trim().toLowerCase();
+	if (!mediaType) return false;
+	return allowed.test(mediaType);
+}
+/**
+* Parse a serialized body string into a JS value, branching on the declared
+* content type.
+*
+* - URL-encoded forms become a flat object so the same `redact` walker works.
+* - Otherwise treat as JSON. Returns `undefined` (NOT `null`, which is a
+*   legitimate JSON value) when parsing fails, so the caller can distinguish
+*   "couldn't parse" from "parsed to literal null".
+*/
+function parseString(text, contentType) {
+	if (contentType && /x-www-form-urlencoded/i.test(contentType)) return Object.fromEntries(new URLSearchParams(text).entries());
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+/**
+* True only for `Object.create(null)` or `{}`-shaped values. Excludes class
+* instances (their prototype chain points somewhere other than Object.prototype
+* or null), streams, FormData, ArrayBuffer views, Buffer, URLSearchParams,
+* and other built-ins that happen to be `typeof === 'object'`.
+*/
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === null || proto === Object.prototype;
+}
+/**
+* Recursively walk `value`, replacing values for denylisted keys with
+* `'[redacted]'` and substituting `'[Circular]'` for any object visited more
+* than once.
+*
+* `seen` is a `WeakSet` of already-visited objects. Carried as a parameter
+* (rather than a closure variable) so the same recursive call can pass it
+* down without per-call allocation.
+*
+* Primitives and `null` pass through unchanged. Arrays preserve order;
+* objects preserve keys.
+*/
+function redact(value, denylist, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return "[Circular]";
+	seen.add(value);
+	if (Array.isArray(value)) return value.map((v) => redact(v, denylist, seen));
+	const out = {};
+	for (const [k, v] of Object.entries(value)) out[k] = denylist.test(k) ? "[redacted]" : redact(v, denylist, seen);
+	return out;
+}
+
+//#endregion
+//#region src/context/headers.ts
+/**
+* Case-insensitively look up a header value. Returns the first defined value
+* for the lowercased name, or undefined. Array values (rare but valid for
+* some headers) are coalesced to the first element since the consumers in
+* this package treat the value as scalar.
+*/
+function findHeader(headers, name) {
+	if (!headers) return void 0;
+	const target = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() !== target) continue;
+		if (value === void 0) continue;
+		return Array.isArray(value) ? value[0] : value;
+	}
+}
+/**
+* Default-redacted header names. The pattern is anchored to the FULL header
+* name (`^...$`) and case-insensitive so it catches `Authorization`,
+* `AUTHORIZATION`, `authorization`, etc. Anchoring matters: an unanchored
+* `cookie` would match `X-Some-Cookie-Hint` too, which we do NOT want — only
+* the exact header by name should be redacted by default.
+*
+* Covers the usual credential carriers (`authorization`, `cookie`, etc) plus
+* common proxy-set headers that often expose client IPs (`forwarded`,
+* `x-forwarded-for`, `x-forwarded-user`). Users add domain-specific entries
+* via `configureNode({ headerDenylist: ... })`.
+*/
+const DEFAULT_HEADER_DENYLIST = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|x-csrf-token|x-xsrf-token|x-auth-token|forwarded|x-forwarded-(?:for|user))$/i;
+/**
+* Combine the built-in denylist with an optional user-supplied one.
+*
+* - No custom regex          -> use the default as-is.
+* - Custom + replace = true  -> use only the custom pattern (with `g`/`y`
+*                               flags stripped so `.test()` stays stateless).
+* - Custom + replace = false -> union: `(?:default)|(?:custom)`, forcing case
+*                               insensitivity since header names are
+*                               case-insensitive over the wire.
+*/
+function resolveHeaderDenylist(custom, replaceDefault = false) {
+	if (!custom) return DEFAULT_HEADER_DENYLIST;
+	if (replaceDefault) return new RegExp(custom.source, custom.flags.replace(/[gy]/g, ""));
+	return new RegExp(`(?:${DEFAULT_HEADER_DENYLIST.source})|(?:${custom.source})`, "i");
+}
+/**
+* Project an HTTP request `headers` object into report attributes.
+*
+* Behavior per header:
+*
+* - **Unset values** (entry exists but the value is `undefined`) are dropped
+*   entirely — `node:http` represents "header was not sent" this way.
+* - **Names are lowercased.** OTel's attribute convention uses lowercase
+*   header keys, and HTTP header names are case-insensitive anyway.
+* - **Allowlist gate.** If `headerAllowlist` is set, only headers whose
+*   lowercased name matches are emitted; everything else is silently dropped
+*   (NOT redacted, dropped). This is the strongest filter — useful for
+*   compliance scenarios where you must opt into headers explicitly.
+* - **Array values** (`set-cookie` can be `string[]`) are joined with `, ` so
+*   the emitted value is a flat string, matching the on-the-wire shape that
+*   most HTTP clients render.
+* - **Denylist redaction.** If the name matches `headerDenylist`, the value
+*   is replaced with `'[redacted]'` (the key still appears so consumers can
+*   tell the header was present).
+*
+* Output keys are `http.request.header.<lowercased-name>`, per OTel.
+*/
+function projectHeaders(headers, options) {
+	const out = {};
+	if (!headers) return out;
+	for (const [rawName, rawValue] of Object.entries(headers)) {
+		if (rawValue === void 0) continue;
+		const name = rawName.toLowerCase();
+		if (options.headerAllowlist && !options.headerAllowlist.test(name)) continue;
+		const value = Array.isArray(rawValue) ? rawValue.join(", ") : rawValue;
+		out[`http.request.header.${name}`] = options.headerDenylist.test(name) ? "[redacted]" : value;
+	}
+	return out;
+}
+
+//#endregion
+//#region src/context/process.ts
+/**
+* Snapshot the Node runtime + host environment at report time and project
+* into OTel-style attribute keys. Cheap (just property reads + a couple of
+* syscalls via `os`), so called per-report rather than cached; this keeps
+* `process.uptime` honest and follows the value of `os.hostname()` if it
+* changes mid-run (unlikely but free correctness).
+*
+* Keys are stable OTel resource attributes; the Flare backend recognizes them.
+*/
+function collectProcessAttributes() {
+	return {
+		"process.runtime.name": "nodejs",
+		"process.runtime.version": process.version,
+		"process.pid": process.pid,
+		"process.uptime": process.uptime(),
+		"host.name": node_os.default.hostname(),
+		"host.arch": process.arch,
+		"os.type": node_os.default.type(),
+		"os.version": node_os.default.release()
+	};
+}
+
+//#endregion
+//#region src/context/collectNode.ts
+/**
+* Build the Node-side `ContextCollector` that core's `Flare` calls on every
+* report. The returned function projects two sources into OTel-style report
+* attributes:
+*
+* 1. **Process info** — runtime version, pid, hostname, etc. Always present.
+* 2. **Active request scope** — method, path/url (with query-string keys
+*    redacted), headers (with the denylist applied), optional body, and
+*    authenticated user. Present when `runWithContext(...)` is active;
+*    falls back to the shared scope otherwise (no request attrs emitted then).
+*
+* Both `provider` and `getOptions` are passed in (not captured by reference to
+* concrete instances) so the closure stays decoupled from `NodeFlare`'s
+* internals. `getOptions` is a getter (not a value) so that `configureNode(...)`
+* changes are visible on subsequent reports without rebuilding the collector.
+*
+* The function returned matches `ContextCollector = (config) => Attributes`,
+* which is core's interface for `Flare`'s third constructor parameter.
+*/
+function makeNodeContextCollector(provider, getOptions) {
+	return (config) => {
+		const attrs = {
+			"flare.entry_point.type": "server",
+			...collectProcessAttributes()
+		};
+		const scope = provider.active();
+		const { request } = scope;
+		if (request.method) attrs["http.request.method"] = request.method;
+		if (request.path) {
+			const queryStart = request.path.indexOf("?");
+			if (queryStart === -1) attrs["url.path"] = request.path;
+			else {
+				attrs["url.path"] = request.path.slice(0, queryStart);
+				const redactedQuery = (0, _flareapp_core.redactUrlQuery)(request.path, config.urlDenylist);
+				const redactedQueryStart = redactedQuery.indexOf("?");
+				attrs["url.query"] = redactedQuery.slice(redactedQueryStart + 1);
+			}
+		}
+		if (request.url) attrs["url.full"] = (0, _flareapp_core.redactUrlQuery)(request.url, config.urlDenylist);
+		const opts = getOptions();
+		Object.assign(attrs, projectHeaders(request.headers, opts));
+		if (opts.captureRequestBody) {
+			const contentType = findHeader(request.headers, "content-type");
+			const body = captureBody(request.body, contentType, opts);
+			if (body !== null) attrs["http.request.body"] = body;
+		}
+		if (scope.user) {
+			if (scope.user.id !== void 0) attrs["enduser.id"] = String(scope.user.id);
+			if (scope.user.email !== void 0) attrs["enduser.email"] = scope.user.email;
+			if (scope.user.username !== void 0) attrs["enduser.username"] = scope.user.username;
+			if (scope.user.ipAddress !== void 0) attrs["client.address"] = scope.user.ipAddress;
+		}
+		return attrs;
+	};
+}
+
+//#endregion
+//#region src/process/fatal.ts
+function buildFatalCallbacks(flare, getOpts, exit = process.exit.bind(process)) {
+	return {
+		async onUncaught(err, origin) {
+			const opts = getOpts();
+			if (opts.uncaughtExceptionMode === "report-and-exit") process.exitCode = 1;
+			const error = err instanceof Error ? err : new Error(String(err));
+			try {
+				await flare.report(error, { "process.uncaught_exception.origin": origin });
+			} catch {}
+			if (opts.uncaughtExceptionMode === "report-and-exit") {
+				await flare.flush(opts.shutdownTimeoutMs);
+				exit(1);
+			}
+		},
+		async onRejection(reason) {
+			const opts = getOpts();
+			if (opts.unhandledRejectionMode === "report-and-exit") process.exitCode = 1;
+			const error = reason instanceof Error ? reason : new Error(String(reason));
+			try {
+				await flare.report(error);
+			} catch {}
+			if (opts.unhandledRejectionMode === "report-and-exit") {
+				await flare.flush(opts.shutdownTimeoutMs);
+				exit(1);
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/process/handlers.ts
+/**
+* Owns the lifecycle of the two process-level error listeners that capture
+* fatal failures and feed them to Flare:
+*
+* - `process.on('uncaughtException', ...)`
+* - `process.on('unhandledRejection', ...)`
+*
+* The manager has two responsibilities:
+*
+* 1. **Reconcile listener state with intent.** Given the current `FatalMode`
+*    for each event (`'off' | 'report' | 'report-and-exit'`), make the actual
+*    listener attachment match: attach when it should be attached but isn't,
+*    detach when it shouldn't be attached but is, no-op when already in the
+*    desired state. This is idempotent — calling `reconcile(...)` repeatedly
+*    with the same options is safe.
+* 2. **Tear down on demand.** `detach()` removes both listeners regardless of
+*    intent, for tests and graceful shutdown.
+*
+* Why keep this separate from `NodeFlare`: the attach/detach logic is purely
+* about Node `process` events and contains no Flare semantics. Isolating it
+* makes it trivial to test (the test suite drives `reconcile()` directly with
+* stub callbacks and asserts on `process.listeners(...)`) and keeps
+* `NodeFlare` focused on report assembly + user-facing API.
+*/
+var ProcessHandlerManager = class {
+	/** The currently-attached listener for `uncaughtException`, or `null`. */
+	uncaughtHandler = null;
+	/** The currently-attached listener for `unhandledRejection`, or `null`. */
+	rejectionHandler = null;
+	constructor(cbs) {
+		this.cbs = cbs;
+	}
+	/**
+	* Bring the attached listeners into agreement with the supplied modes.
+	* Idempotent: when current state already matches intent, this is a no-op.
+	*/
+	reconcile(opts) {
+		this.reconcileOne("uncaughtException", opts.uncaughtExceptionMode, () => this.uncaughtHandler, (h) => {
+			this.uncaughtHandler = h;
+		}, (err, origin) => this.cbs.onUncaught(err, origin));
+		this.reconcileOne("unhandledRejection", opts.unhandledRejectionMode, () => this.rejectionHandler, (h) => {
+			this.rejectionHandler = h;
+		}, (reason) => this.cbs.onRejection(reason));
+	}
+	/**
+	* Remove both listeners regardless of current intent. Used by tests and by
+	* `NodeFlare.removeProcessListeners()`. Safe to call when nothing is
+	* attached.
+	*/
+	detach() {
+		if (this.uncaughtHandler) {
+			process.off("uncaughtException", this.uncaughtHandler);
+			this.uncaughtHandler = null;
+		}
+		if (this.rejectionHandler) {
+			process.off("unhandledRejection", this.rejectionHandler);
+			this.rejectionHandler = null;
+		}
+	}
+	/**
+	* Generic attach/detach for one event. The `get`/`set` closures let us
+	* share this body between the two events while still mutating distinct
+	* fields (`uncaughtHandler` vs `rejectionHandler`).
+	*
+	* Truth table:
+	* - intent off, currently attached -> detach
+	* - intent off, not attached       -> no-op
+	* - intent on,  currently attached -> no-op (already correct)
+	* - intent on,  not attached       -> attach
+	*/
+	reconcileOne(event, mode, get, set, impl) {
+		const current = get();
+		const wants = mode !== "off";
+		if (wants && !current) {
+			set(impl);
+			process.on(event, impl);
+		} else if (!wants && current) {
+			process.off(event, current);
+			set(null);
+		}
+	}
+};
+
+//#endregion
+//#region src/scope/NodeScope.ts
+var NodeScope = class extends _flareapp_core.Scope {
+	request = {};
+	user = null;
+};
+
+//#endregion
+//#region src/scope/AsyncLocalStorageScopeProvider.ts
+/**
+* `ScopeProvider` implementation that gives every in-flight request its own
+* `NodeScope`, isolated from concurrent requests.
+*
+* Built on Node's `node:async_hooks#AsyncLocalStorage`: when code runs inside
+* `als.run(scope, fn)`, every `als.getStore()` call from within `fn` (and any
+* async work `fn` awaits, including timers, promises, `process.nextTick`, etc)
+* returns that `scope`. Outside any `als.run` call, `getStore()` returns
+* `undefined`. This is the same primitive that lets observability libraries
+* propagate trace context across async boundaries without manual plumbing.
+*
+* Two "kinds of read" surfaced separately:
+*
+* - `active()` — never returns null. The internal read used by `Flare` for
+*   every glow, attribute set, and report. When called inside `runWithContext`,
+*   returns the per-request `NodeScope`. Outside, returns a shared `fallback`
+*   scope so glows/attributes/reports issued outside any request still have
+*   somewhere to land (process-level reports, startup errors, scheduled jobs).
+* - `getContext()` — public debug helper. Returns `null` outside any
+*   `runWithContext`, so consumers can distinguish "I am inside a request" from
+*   "I am not". The fallback is intentionally NOT exposed here.
+*
+* The fallback is also a per-instance `NodeScope` so that writes from outside
+* a request scope persist for subsequent outside-scope reports.
+*/
+var AsyncLocalStorageScopeProvider = class {
+	als = new node_async_hooks.AsyncLocalStorage();
+	fallback = new NodeScope();
+	/**
+	* Internal: returns the per-request scope when inside `runWithContext`,
+	* or the shared fallback otherwise. Always returns a real `NodeScope`.
+	*/
+	active() {
+		return this.als.getStore() ?? this.fallback;
+	}
+	/**
+	* Public: returns the per-request scope when inside `runWithContext`, or
+	* `null` otherwise. Useful for assertions like "am I in a request?".
+	*/
+	getContext() {
+		return this.als.getStore() ?? null;
+	}
+	/**
+	* Open a fresh request scope around `fn` and run it. Every async hop
+	* inside `fn` (awaits, timers, promise chains) sees the same scope via
+	* `active()`/`getContext()`; concurrent calls each get their own.
+	*
+	* `request` is shallow-cloned so later edits to the caller's object do not
+	* leak into the stored scope.
+	*/
+	runWithContext(request, fn) {
+		const scope = new NodeScope();
+		scope.request = { ...request };
+		return this.als.run(scope, fn);
+	}
+	/**
+	* Patch the current scope's `request` shape. When called inside
+	* `runWithContext`, the patch is visible to all subsequent reads from
+	* within the same request chain. When called outside, the patch lands on
+	* the fallback scope.
+	*/
+	mergeContext(partial) {
+		const scope = this.als.getStore() ?? this.fallback;
+		scope.request = {
+			...scope.request,
+			...partial
+		};
+	}
+	/**
+	* Set the authenticated user on the current scope. Same in-scope vs
+	* fallback semantics as `mergeContext`.
+	*/
+	setUser(user) {
+		const scope = this.als.getStore() ?? this.fallback;
+		scope.user = user;
+	}
+};
+
+//#endregion
+//#region src/stacktrace/DiskFileReader.ts
+/**
+* Node `FileReader` implementation that reads source files from disk.
+*
+* Wired into `@flareapp/node`'s singleton so the stack-trace builder can pull
+* source for each frame and render a snippet. On the server the frame's "URL"
+* is usually a local path (e.g. `/app/dist/server.js`) or a `file://` URL
+* (from `import.meta.url`), so we resolve straight off disk instead of going
+* over the network.
+*
+* Safety gates:
+*
+* 1. **Local-path allowlist.** Only `file://` URLs and absolute filesystem
+*    paths (POSIX `/foo`, Windows `C:\foo` or `\\server\share\foo`) are
+*    accepted. HTTP URLs and relative paths return `null` immediately. We
+*    refuse to read anything that does not unambiguously identify a local
+*    file — no surprise traversal, no following http stack frames in a
+*    server build, no relative-path ambiguity around the current working
+*    directory.
+* 2. **Catch-all.** Missing files, permission errors, and any other failure
+*    return `null`. The `read()` contract returns `null` on every failure
+*    path and never throws.
+*
+* `fileURLToPath` is used when the input is a `file://` URL so we hand
+* `readFile` a real OS path. Otherwise the URL IS already a path and is
+* passed through unchanged.
+*/
+var DiskFileReader = class {
+	async read(url) {
+		if (!isLocalFileUrl(url)) return null;
+		try {
+			return await (0, node_fs_promises.readFile)(/^file:\/\//i.test(url) ? (0, node_url.fileURLToPath)(url) : url, "utf-8");
+		} catch {
+			return null;
+		}
+	}
+};
+/**
+* Return true when `url` is something we are willing to treat as a local
+* file. Matches four shapes:
+*
+* - `file://...` URLs (any casing of the scheme)
+* - POSIX absolute paths starting with `/`
+* - Windows drive-letter paths like `C:\foo` or `c:/foo`
+* - Windows UNC paths starting with `\\`
+*
+* Anything else (relative paths, http, data, blob, etc) is rejected.
+*/
+function isLocalFileUrl(url) {
+	return /^file:\/\//i.test(url) || url.startsWith("/") || /^[a-z]:[\\/]/i.test(url) || url.startsWith("\\\\");
+}
+
+//#endregion
+//#region src/Flare.ts
+const NODE_SDK_NAME = "@flareapp/node";
+const NODE_SDK_VERSION = typeof process !== "undefined" && true ? "0.1.1" : "?";
+/**
+* Strip the `g` and `y` flags from a user-supplied regex.
+*
+* `RegExp.prototype.test()` and `.exec()` keep `lastIndex` state when either of
+* these flags is set, which means reusing the same regex across many keys (as
+* the header denylist and body redaction do) silently skips matches after the
+* first hit. Reconstructing the regex without those flags gives stateless
+* matching while preserving everything else (`i`, `m`, `s`, `u`, source).
+*/
+function sanitizeRegex(re) {
+	const safeFlags = re.flags.replace(/[gy]/g, "");
+	return new RegExp(re.source, safeFlags);
+}
+const DEFAULT_NODE_OPTIONS = {
+	uncaughtExceptionMode: "report-and-exit",
+	unhandledRejectionMode: "report-and-exit",
+	shutdownTimeoutMs: 2e3,
+	headerDenylist: DEFAULT_HEADER_DENYLIST,
+	headerAllowlist: null,
+	replaceDefaultHeaderDenylist: false,
+	captureRequestBody: false,
+	bodyMaxBytes: 16384,
+	bodyAllowedContentTypes: DEFAULT_BODY_CONTENT_TYPES,
+	bodyKeyDenylist: DEFAULT_BODY_KEY_DENYLIST
+};
+/**
+* Node.js-specific `Flare` singleton, exposed from `@flareapp/node` as `flare`.
+*
+* Subclasses core's `Flare` and wires the Node-only seams in its constructor:
+*
+* - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback
+*   gets its own `NodeScope` (glows, attributes, user, entry-point, request),
+*   isolated from concurrent requests.
+* - `makeNodeContextCollector(...)` to project the current `NodeScope` and
+*   process info into report attributes (http.request.*, url.path, etc).
+* - `DiskFileReader` to read source files for stack-trace snippets via
+*   `node:fs/promises` instead of the browser's `fetch`.
+* - `ProcessHandlerManager` to attach/detach `uncaughtException` and
+*   `unhandledRejection` listeners based on the current `NodeOptions`.
+*
+* Also adds Node-only API surface on top of core: `configureNode(...)`,
+* `runWithContext(...)`, `mergeContext(...)`, `setUser(...)`, `getContext()`,
+* `removeProcessListeners()`. Inherited core methods (`light`, `configure`,
+* `addContext`, `glow`, etc.) return `this`, so chaining keeps the
+* `NodeFlare` type and `configureNode(...)` stays callable mid-chain.
+*/
+var NodeFlare = class extends _flareapp_core.Flare {
+	nodeOptions = { ...DEFAULT_NODE_OPTIONS };
+	isLit = false;
+	nodeScopeProvider;
+	handlerManager;
+	constructor() {
+		const scopeProvider = new AsyncLocalStorageScopeProvider();
+		const collector = makeNodeContextCollector(scopeProvider, () => this.nodeOptions);
+		super(new _flareapp_core.Api(), collector, new DiskFileReader(), scopeProvider);
+		this.nodeScopeProvider = scopeProvider;
+		this.setSdkInfo({
+			name: NODE_SDK_NAME,
+			version: NODE_SDK_VERSION
+		});
+		this.handlerManager = new ProcessHandlerManager(buildFatalCallbacks(this, () => this.nodeOptions));
+	}
+	/**
+	* Set the API key (and optional debug flag), then reconcile process
+	* listeners with the current `nodeOptions`. Reconcile runs on EVERY call,
+	* not just the first, so `light()` is the right escape hatch to re-attach
+	* after `removeProcessListeners()`.
+	*/
+	light(key, debug) {
+		super.light(key, debug);
+		this.isLit = true;
+		this.handlerManager.reconcile(this.nodeOptions);
+		return this;
+	}
+	/**
+	* Merge Node-only options (fatal-handler modes, header/body redaction
+	* config, shutdown timeout) into the active configuration. Safe to call
+	* before or after `light()`:
+	*
+	* - Before `light()`: options are stored; listeners are attached when
+	*   `light()` runs.
+	* - After `light()`: options are stored AND listeners are reconciled
+	*   immediately, so flipping a mode to `'off'` detaches the handler and
+	*   flipping it back to `'report'`/`'report-and-exit'` re-attaches.
+	*
+	* Regex options (`headerAllowlist`, `bodyAllowedContentTypes`,
+	* `bodyKeyDenylist`) are passed through `sanitizeRegex` to strip stateful
+	* `g`/`y` flags; without that, `RegExp.prototype.test` would skip matches
+	* across keys.
+	*/
+	configureNode(partial) {
+		if (partial.headerDenylist !== void 0 || partial.replaceDefaultHeaderDenylist !== void 0) {
+			this.nodeOptions.headerDenylist = resolveHeaderDenylist(partial.headerDenylist ?? void 0, partial.replaceDefaultHeaderDenylist ?? this.nodeOptions.replaceDefaultHeaderDenylist);
+			this.nodeOptions.replaceDefaultHeaderDenylist = partial.replaceDefaultHeaderDenylist ?? this.nodeOptions.replaceDefaultHeaderDenylist;
+		}
+		if (partial.headerAllowlist !== void 0) this.nodeOptions.headerAllowlist = partial.headerAllowlist === null ? null : sanitizeRegex(partial.headerAllowlist);
+		if (partial.uncaughtExceptionMode !== void 0) this.nodeOptions.uncaughtExceptionMode = partial.uncaughtExceptionMode;
+		if (partial.unhandledRejectionMode !== void 0) this.nodeOptions.unhandledRejectionMode = partial.unhandledRejectionMode;
+		if (partial.shutdownTimeoutMs !== void 0) this.nodeOptions.shutdownTimeoutMs = partial.shutdownTimeoutMs;
+		if (partial.captureRequestBody !== void 0) this.nodeOptions.captureRequestBody = partial.captureRequestBody;
+		if (partial.bodyMaxBytes !== void 0) this.nodeOptions.bodyMaxBytes = partial.bodyMaxBytes;
+		if (partial.bodyAllowedContentTypes !== void 0) this.nodeOptions.bodyAllowedContentTypes = sanitizeRegex(partial.bodyAllowedContentTypes);
+		if (partial.bodyKeyDenylist !== void 0) this.nodeOptions.bodyKeyDenylist = sanitizeRegex(partial.bodyKeyDenylist);
+		if (this.isLit) this.handlerManager.reconcile(this.nodeOptions);
+		return this;
+	}
+	/**
+	* Run `fn` inside a fresh `NodeScope` carrying the supplied request
+	* metadata. Inside `fn` (and any async work it awaits), `flare.glow(...)`,
+	* `flare.addContext(...)`, `flare.setUser(...)`, and `flare.report(...)`
+	* see a scope that is isolated from other concurrent requests.
+	*
+	* Mirrors a typical web-framework middleware: call once per request,
+	* wrapping the request handler, and the SDK will attribute any error
+	* reported inside the chain to the right request.
+	*/
+	runWithContext(request, fn) {
+		return this.nodeScopeProvider.runWithContext(request, fn);
+	}
+	/**
+	* Patch the request metadata on the active scope after `runWithContext(...)`
+	* has already started. Useful when fields become known partway through a
+	* request (e.g., the resolved absolute URL after proxy headers are parsed).
+	*
+	* Outside any `runWithContext(...)` callback, this writes to the fallback
+	* scope; the patch is visible to subsequent reports issued from outside a
+	* request scope but is NOT inherited by future `runWithContext(...)` calls.
+	*/
+	mergeContext(partial) {
+		this.nodeScopeProvider.mergeContext(partial);
+	}
+	/**
+	* Attach an authenticated user to the active scope. Inside a request scope
+	* this is per-request; outside it lands on the fallback scope. The fields
+	* are projected to OTel-style keys (`enduser.id`, `enduser.email`,
+	* `enduser.username`, `client.address`) by the Node context collector.
+	*/
+	setUser(user) {
+		this.nodeScopeProvider.setUser(user);
+	}
+	/**
+	* Returns the request scope when called inside `runWithContext(...)`, or
+	* `null` outside. Intentionally returns `null` (not the fallback scope)
+	* when no request is active, so callers can distinguish "we are inside a
+	* request" from "we are not". Primarily useful for debugging.
+	*/
+	getContext() {
+		return this.nodeScopeProvider.getContext();
+	}
+	/**
+	* Detach the `uncaughtException` and `unhandledRejection` listeners
+	* without changing `nodeOptions`. Intended for tests and for graceful
+	* shutdown paths where you want to take ownership of process exit
+	* yourself.
+	*
+	* Calling `light()` afterwards re-attaches based on the current options.
+	*/
+	removeProcessListeners() {
+		this.handlerManager.detach();
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const flare = new NodeFlare();
+
+//#endregion
+Object.defineProperty(exports, 'DEFAULT_URL_DENYLIST', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.DEFAULT_URL_DENYLIST;
+  }
+});
+Object.defineProperty(exports, 'Flare', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.Flare;
+  }
+});
+Object.defineProperty(exports, 'GlobalScopeProvider', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.GlobalScopeProvider;
+  }
+});
+exports.NodeFlare = NodeFlare;
+exports.NodeScope = NodeScope;
+Object.defineProperty(exports, 'NullFileReader', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.NullFileReader;
+  }
+});
+Object.defineProperty(exports, 'Scope', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.Scope;
+  }
+});
+Object.defineProperty(exports, 'convertToError', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.convertToError;
+  }
+});
+exports.flare = flare;
+Object.defineProperty(exports, 'redactUrlQuery', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.redactUrlQuery;
+  }
+});
+Object.defineProperty(exports, 'resolveDenylist', {
+  enumerable: true,
+  get: function () {
+    return _flareapp_core.resolveDenylist;
+  }
+});