@next-rsc-debug/core 0.1.9 → 0.2.0

package/README.md

@@ -9,6 +9,9 @@ Framework-independent event protocol and collector for Next RSC Debug.
 - In-memory ring buffer (default 5000 events)
 - Event subscription support
 - URL sanitization utilities
+- Metadata sanitization: sensitive keys stripped, values normalized to be
+  JSON-safe, applied centrally in `createEvent`
+- Cache key redaction for email addresses
 - Analyzer primitives (slow request, duplicate request, error detection)
 - Warning detection
 
@@ -33,6 +36,30 @@ const events = getCollector().list();
 const { warnings } = analyzeEvents(events);
 ```
 
+## Sanitization
+
+`createEvent` runs every `metadata` object through `sanitizeMetadata` before the
+event is returned, so sensitive keys and unserializable values cannot reach the
+collector — and from there any SSE stream — regardless of which producer
+supplied them:
+
+```ts
+createEvent({
+  type: "cache:hit",
+  metadata: {
+    key: "post:1",
+    authorization: "Bearer secret", // stripped
+    at: new Date(), // normalized to an ISO string
+  },
+});
+// metadata === { key: "post:1", at: "2026-09-29T…" }
+```
+
+`stripSensitiveQueryParams` is reachable through
+`sanitizeUrl(url, { preserveQuery: true })`, which keeps non-sensitive query
+parameters for display and duplicate detection while still removing sensitive
+ones and embedded credentials.
+
 ## License
 
 MIT

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG9D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjD,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAEzE,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,cAAmB,GAC3B;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;CAAE,CA0EzB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE9D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAEnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAI9D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE9D"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG9D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjD,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,mBAAmB,GAAG,OAAO,CAAC;AAEzE,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE,cAAmB,GAC3B;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;CAAE,CA8EzB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE9D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAEnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAI9D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE/D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAE9D"}

package/dist/analyzer.js

@@ -29,11 +29,15 @@ export function analyzeEvents(events, options = {}) {
             });
         }
     }
-    // Duplicate detection: group fetch events by normalized URL.
+    // Duplicate detection: group fetch events by normalized URL. Non-sensitive
+    // query parameters are preserved so `/api/items?page=1` and
+    // `/api/items?page=2` are not reported as duplicates of each other.
     const fetchGroups = new Map();
     for (const event of events) {
         if (event.type === "fetch:end" && event.metadata?.url) {
-            const url = sanitizeUrl(String(event.metadata.url));
+            const url = sanitizeUrl(String(event.metadata.url), {
+                preserveQuery: true,
+            });
             const group = fetchGroups.get(url);
             if (group) {
                 group.push(event);
@@ -83,7 +87,7 @@ export function normalizeFetchUrl(event) {
     if (event.type !== "fetch:end" || !event.metadata?.url) {
         return undefined;
     }
-    return sanitizeUrl(String(event.metadata.url));
+    return sanitizeUrl(String(event.metadata.url), { preserveQuery: true });
 }
 export function isFetchEventType(type) {
     return type === "fetch:start" || type === "fetch:end";

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,gBAAgB,GAChB,WAAW,GACX,SAAS,GACT,aAAa,GACb,WAAW,GACX,WAAW,GACX,YAAY,GACZ,kBAAkB,GAClB,cAAc,GACd,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAkBD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU,CAmBnE"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,gBAAgB,GAChB,WAAW,GACX,SAAS,GACT,aAAa,GACb,WAAW,GACX,WAAW,GACX,YAAY,GACZ,kBAAkB,GAClB,cAAc,GACd,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAkBD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU,CAuBnE"}

package/dist/events.js

@@ -4,6 +4,7 @@
  * Every event has a unique ID, timestamp, and type.
  * Optional fields: duration, requestId, parentId, metadata.
  */
+import { sanitizeMetadata } from "./sanitize.js";
 let idCounter = 0;
 let lastTimestamp = 0;
 function generateId(prefix) {
@@ -43,8 +44,12 @@ export function createEvent(options) {
     if (options.duration !== undefined) {
         event.duration = options.duration;
     }
-    if (options.metadata !== undefined) {
-        event.metadata = options.metadata;
+    // Sanitized here, at the single point every event is constructed, so that
+    // sensitive keys and unserializable values cannot reach the collector — and
+    // from there the SSE stream — no matter which producer supplied them.
+    const metadata = sanitizeMetadata(options.metadata);
+    if (metadata !== undefined) {
+        event.metadata = metadata;
     }
     return event;
 }

package/dist/index.d.ts

@@ -2,8 +2,8 @@
  * Public API for @next-rsc-debug/core.
  */
 export { createEvent, createEventId, createRequestId, createNavigationId, type DebugEvent, type DebugEventType, type CreateEventOptions, } from "./events.js";
-export { sanitizeUrl, stripSensitiveQueryParams, isSafeKey, } from "./sanitize.js";
-export { RingBuffer, type EventListener, type Unsubscribe, type RingBufferOptions, } from "./ring-buffer.js";
+export { sanitizeUrl, stripSensitiveQueryParams, isSafeKey, sanitizeKey, sanitizeMetadata, type SanitizeUrlOptions, type SanitizeMetadataOptions, } from "./sanitize.js";
+export { RingBuffer, DEFAULT_MAX_EVENTS, type EventListener, type Unsubscribe, type RingBufferOptions, } from "./ring-buffer.js";
 export { analyzeEvents, type Warning, type WarningType, type WarningSeverity, type AnalyzeOptions, normalizeFetchUrl, isFetchEventType, isNavigationEventType, isRscEventType, isCacheEventType, isActionEventType, isErrorEventType, } from "./analyzer.js";
 export { getCollector, createCollector, setCollector, resetCollector, type Collector, } from "./collector.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,yBAAyB,EACzB,SAAS,GACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,UAAU,EACV,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,KAAK,SAAS,GACf,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,yBAAyB,EACzB,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,KAAK,SAAS,GACf,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -2,7 +2,7 @@
  * Public API for @next-rsc-debug/core.
  */
 export { createEvent, createEventId, createRequestId, createNavigationId, } from "./events.js";
-export { sanitizeUrl, stripSensitiveQueryParams, isSafeKey, } from "./sanitize.js";
-export { RingBuffer, } from "./ring-buffer.js";
+export { sanitizeUrl, stripSensitiveQueryParams, isSafeKey, sanitizeKey, sanitizeMetadata, } from "./sanitize.js";
+export { RingBuffer, DEFAULT_MAX_EVENTS, } from "./ring-buffer.js";
 export { analyzeEvents, normalizeFetchUrl, isFetchEventType, isNavigationEventType, isRscEventType, isCacheEventType, isActionEventType, isErrorEventType, } from "./analyzer.js";
 export { getCollector, createCollector, setCollector, resetCollector, } from "./collector.js";

package/dist/ring-buffer.d.ts

@@ -15,6 +15,12 @@ export type Unsubscribe = () => void;
 export interface RingBufferOptions {
     max?: number;
 }
+/**
+ * Shared by the server-side ring buffer and the client-side event list, so the
+ * two cannot drift apart and leave the UI holding more history than the server
+ * is willing to keep.
+ */
+export declare const DEFAULT_MAX_EVENTS = 5000;
 export declare class RingBuffer {
     private readonly max;
     private events;

package/dist/ring-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../src/ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAuB;gBAE5B,OAAO,GAAE,iBAAsB;IAO3C,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAgB7B,IAAI,IAAI,UAAU,EAAE;IAIpB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE;IAOnD,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW;IAU/C,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,IAAI,IAAI;CAIhB"}
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../src/ring-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAuB;gBAE5B,OAAO,GAAE,iBAAsB;IAO3C,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAgB7B,IAAI,IAAI,UAAU,EAAE;IAIpB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE;IAOnD,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW;IAU/C,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,IAAI,IAAI;CAIhB"}

package/dist/ring-buffer.js

@@ -9,13 +9,18 @@
  * - Safe concurrent usage in Node.js.
  * - No memory leaks.
  */
-const DEFAULT_MAX = 5000;
+/**
+ * Shared by the server-side ring buffer and the client-side event list, so the
+ * two cannot drift apart and leave the UI holding more history than the server
+ * is willing to keep.
+ */
+export const DEFAULT_MAX_EVENTS = 5000;
 export class RingBuffer {
     max;
     events = [];
     listeners = [];
     constructor(options = {}) {
-        this.max = options.max ?? DEFAULT_MAX;
+        this.max = options.max ?? DEFAULT_MAX_EVENTS;
         if (!Number.isFinite(this.max) || this.max <= 0) {
             throw new Error("RingBuffer max must be a positive number");
         }

package/dist/sanitize.d.ts

@@ -7,7 +7,35 @@
  * - Never store cookies, auth headers, request bodies, response bodies,
  *   passwords, or tokens.
  */
-export declare function sanitizeUrl(url: string): string;
+export interface SanitizeUrlOptions {
+    /**
+     * Keep non-sensitive query parameters instead of dropping the whole query
+     * string. Use this for display and duplicate detection, where
+     * `/api/items?page=1` and `/api/items?page=2` are genuinely different
+     * requests. Sensitive parameters are still removed either way.
+     *
+     * Defaults to `false`, which strips the query string entirely — the more
+     * conservative choice.
+     */
+    preserveQuery?: boolean;
+}
+export declare function sanitizeUrl(url: string, options?: SanitizeUrlOptions): string;
 export declare function stripSensitiveQueryParams(url: string): string;
 export declare function isSafeKey(key: string): boolean;
+export declare function sanitizeKey(key: string): string;
+export interface SanitizeMetadataOptions {
+    maxDepth?: number;
+    maxArrayItems?: number;
+    maxStringLength?: number;
+}
+/**
+ * Strips sensitive keys and makes every remaining value JSON-safe.
+ *
+ * Guards two failure modes at once:
+ *   - leakage: an auth token handed to `debugCacheHit()` would otherwise be
+ *     persisted and streamed to every connected client
+ *   - serialization: a circular reference or BigInt in metadata would throw in
+ *     `JSON.stringify` and break the SSE stream
+ */
+export declare function sanitizeMetadata(metadata: Record<string, unknown> | undefined, options?: SanitizeMetadataOptions): Record<string, unknown> | undefined;
 //# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyB/C;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+B7D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM9C"}
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AASD,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAyBR;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+B7D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAM9C;AAeD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAe/C;AAUD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AA2HD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAkBrC"}

package/dist/sanitize.js

@@ -28,10 +28,19 @@ const SENSITIVE_QUERY_PARAMS = new Set([
     "private_key",
     "client_secret",
 ]);
-export function sanitizeUrl(url) {
+/** Removes `user:password@` and `user@` prefixes from a URL. */
+function stripCredentials(url) {
+    return url
+        .replace(/^(https?:\/\/)[^:/@\s]+:[^@/\s]+@/, "$1")
+        .replace(/^(https?:\/\/)[^@/\s]+@/, "$1");
+}
+export function sanitizeUrl(url, options = {}) {
     if (typeof url !== "string" || url.length === 0) {
         return "";
     }
+    if (options.preserveQuery) {
+        return stripSensitiveQueryParams(url);
+    }
     let sanitized;
     try {
         const parsed = new URL(url);
@@ -46,10 +55,7 @@ export function sanitizeUrl(url) {
         sanitized = url.split("?")[0].split("#")[0];
     }
     // Also strip credentials embedded in the URL (user:pass@host).
-    sanitized = sanitized.replace(/^(https?:\/\/)[^:/@\s]+:[^@/\s]+@/, "$1");
-    // Remove userinfo entirely if present (user@host without password).
-    sanitized = sanitized.replace(/^(https?:\/\/)[^@/\s]+@/, "$1");
-    return sanitized;
+    return stripCredentials(sanitized);
 }
 export function stripSensitiveQueryParams(url) {
     if (typeof url !== "string" || url.length === 0) {
@@ -60,24 +66,24 @@ export function stripSensitiveQueryParams(url) {
         parsed = new URL(url);
     }
     catch {
-        return url.split("#")[0];
+        return stripCredentials(url.split("#")[0]);
     }
     const params = parsed.searchParams;
     const sensitiveKeys = [];
     for (const key of params.keys()) {
-        if (SENSITIVE_QUERY_PARAMS.has(key.toLowerCase())) {
+        if (!isSafeKey(key)) {
             sensitiveKeys.push(key);
         }
     }
     if (sensitiveKeys.length === 0) {
-        return url.split("#")[0];
+        return stripCredentials(url.split("#")[0]);
     }
     for (const key of sensitiveKeys) {
         params.delete(key);
     }
     parsed.search = params.toString();
     parsed.hash = "";
-    return parsed.toString();
+    return stripCredentials(parsed.toString());
 }
 export function isSafeKey(key) {
     if (typeof key !== "string") {
@@ -86,3 +92,157 @@ export function isSafeKey(key) {
     const lower = key.toLowerCase();
     return !SENSITIVE_QUERY_PARAMS.has(lower);
 }
+/* -------------------------------------------------------------------------- */
+/* Cache key redaction                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Deliberately narrow: only email addresses, which are high-confidence PII
+ * with a distinctive shape. Attempting to also detect phone numbers, national
+ * ids or opaque user ids would mangle legitimate cache keys, and a wrong guess
+ * is worse than no redaction for a debugging tool. Anything beyond this is an
+ * application-level decision about which identifiers are safe to log.
+ */
+const EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+export function sanitizeKey(key) {
+    if (typeof key !== "string" || key.length === 0) {
+        return "";
+    }
+    return key.replace(EMAIL_PATTERN, (match) => {
+        const at = match.lastIndexOf("@");
+        if (at <= 0) {
+            return "[redacted]";
+        }
+        const local = match.slice(0, at);
+        const domain = match.slice(at + 1);
+        // Keep enough to correlate events about the same user without retaining
+        // the address itself.
+        return `${local[0]}***@${domain}`;
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* Metadata sanitization                                                      */
+/* -------------------------------------------------------------------------- */
+const DEFAULT_MAX_DEPTH = 6;
+const DEFAULT_MAX_ARRAY_ITEMS = 100;
+const DEFAULT_MAX_STRING_LENGTH = 2000;
+function truncate(value, max) {
+    if (value.length <= max) {
+        return value;
+    }
+    return `${value.slice(0, max)}… [truncated ${value.length - max} chars]`;
+}
+/**
+ * Converts an arbitrary value into something `JSON.stringify` can always
+ * handle, and that is safe to broadcast to every connected browser.
+ *
+ * Applied centrally in `createEvent` rather than at each call site, so that a
+ * new producer cannot accidentally bypass it.
+ */
+function normalizeValue(value, depth, seen, limits) {
+    if (value === null) {
+        return null;
+    }
+    const type = typeof value;
+    if (type === "string") {
+        return truncate(value, limits.maxStringLength);
+    }
+    if (type === "boolean") {
+        return value;
+    }
+    if (type === "number") {
+        // NaN/Infinity serialize to null, which reads as "missing" downstream.
+        return Number.isFinite(value) ? value : String(value);
+    }
+    if (type === "bigint") {
+        // JSON.stringify throws on BigInt.
+        return value.toString();
+    }
+    if (type === "function" || type === "symbol" || type === "undefined") {
+        return undefined;
+    }
+    const obj = value;
+    // Path-scoped cycle detection: a repeated reference in a tree that is not
+    // actually cyclic is fine, only a reference back into the current path.
+    if (seen.has(obj)) {
+        return "[Circular]";
+    }
+    if (depth >= limits.maxDepth) {
+        return "[Max depth reached]";
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value.toISOString();
+    }
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: truncate(value.message, limits.maxStringLength),
+        };
+    }
+    seen.add(obj);
+    try {
+        if (Array.isArray(value)) {
+            const items = [];
+            for (const item of value.slice(0, limits.maxArrayItems)) {
+                const normalized = normalizeValue(item, depth + 1, seen, limits);
+                items.push(normalized === undefined ? null : normalized);
+            }
+            if (value.length > limits.maxArrayItems) {
+                items.push(`[${value.length - limits.maxArrayItems} more items]`);
+            }
+            return items;
+        }
+        if (value instanceof Map) {
+            return normalizeValue(Object.fromEntries(value), depth, seen, limits);
+        }
+        if (value instanceof Set) {
+            return normalizeValue([...value], depth, seen, limits);
+        }
+        return normalizeRecord(value, depth, seen, limits);
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+function normalizeRecord(source, depth, seen, limits) {
+    const out = {};
+    for (const [key, raw] of Object.entries(source)) {
+        // Applied at every level, so `{ user: { token: "…" } }` is cleaned too.
+        if (!isSafeKey(key)) {
+            continue;
+        }
+        const value = normalizeValue(raw, depth + 1, seen, limits);
+        if (value === undefined) {
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Strips sensitive keys and makes every remaining value JSON-safe.
+ *
+ * Guards two failure modes at once:
+ *   - leakage: an auth token handed to `debugCacheHit()` would otherwise be
+ *     persisted and streamed to every connected client
+ *   - serialization: a circular reference or BigInt in metadata would throw in
+ *     `JSON.stringify` and break the SSE stream
+ */
+export function sanitizeMetadata(metadata, options = {}) {
+    if (metadata === undefined || metadata === null) {
+        return undefined;
+    }
+    if (typeof metadata !== "object" || Array.isArray(metadata)) {
+        return undefined;
+    }
+    const limits = {
+        maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxArrayItems: options.maxArrayItems ?? DEFAULT_MAX_ARRAY_ITEMS,
+        maxStringLength: options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH,
+    };
+    // Seed the root into the cycle set. `normalizeValue` relies on the invariant
+    // that the object it is about to walk is already on the path, so without this
+    // a self-referencing root would be expanded one level before being caught.
+    const seen = new WeakSet();
+    seen.add(metadata);
+    return normalizeRecord(metadata, 0, seen, limits);
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@next-rsc-debug/core",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Framework-independent event protocol and collector for Next RSC Debug",
   "author": "Samith Mendis",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -19,7 +20,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run --config vitest.config.ts"
+    "test": "vitest run --config vitest.config.ts",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0 <6.1.0"