@graphorin/server 0.5.0

package/dist/commentary/sanitizer.js

@@ -0,0 +1,182 @@
+import { DEFAULT_APPLY_TO_EVENTS, DEFAULT_DELIVERY_COMMENTARY_PATTERNS } from "./built-in-patterns.js";
+import { createHash } from "node:crypto";
+
+//#region src/commentary/sanitizer.ts
+/**
+* Stateless delivery-layer commentary-phase trace sanitizer. Walks
+* outbound `ServerMessage` event frames and applies the configured
+* pattern catalogue to the JSON-stringified payload; matched
+* fragments are wrapped in the configured envelope (default) or
+* stripped (per the `'strip'` policy) or passed through (per the
+* `'pass-through'` policy — operator opt-out for trusted
+* deployments).
+*
+* The sanitizer runs AFTER the `ServerMessage` Zod-validation pass
+* in `@graphorin/protocol` and BEFORE the message hits the wire (so
+* the protocol schema is unchanged; the sanitization is a pure
+* transform applied to validated payloads). It is bytes-equal across
+* the WS / SSE / REST transports — the same input + same policy
+* produces the same output regardless of which transport invoked
+* the sanitizer.
+*
+* @packageDocumentation
+*/
+const DEFAULT_OPEN = "<<<commentary>>>";
+const DEFAULT_CLOSE = "<<</commentary>>>";
+/**
+* Build a stateless delivery-layer sanitizer. Tests can swap the
+* `sink` for an in-memory recorder; production wires the
+* `@graphorin/security/audit` `appendAudit` helper.
+*
+* @stable
+*/
+function createDeliveryCommentarySanitizer(config = {}) {
+	const policy = config.policy ?? "wrap";
+	const applyToEvents = config.applyToEvents ?? DEFAULT_APPLY_TO_EVENTS;
+	const applyToSet = new Set(applyToEvents);
+	const patterns = config.patterns ?? DEFAULT_DELIVERY_COMMENTARY_PATTERNS;
+	const open = config.wrapOpen ?? DEFAULT_OPEN;
+	const close = config.wrapClose ?? DEFAULT_CLOSE;
+	const sink = config.sink;
+	function sanitize(frame, transport) {
+		if (policy === "pass-through") return frame;
+		if (!applyToSet.has(frame.type)) return frame;
+		const before = JSON.stringify(frame.payload ?? null);
+		const allReasons = /* @__PURE__ */ new Set();
+		let mutated = false;
+		const next = walkAndSanitize(frame.payload, (text) => {
+			const out = applyToText(text, patterns, policy, open, close);
+			for (const reason of out.reasons) allReasons.add(reason);
+			if (out.transformed !== text) mutated = true;
+			return out.transformed;
+		});
+		if (!mutated) return frame;
+		const after = JSON.stringify(next ?? null);
+		const decision = {
+			transport,
+			boundary: "event-emission",
+			policy,
+			applied: true,
+			reasons: [...allReasons],
+			matchedPattern: [...allReasons][0],
+			sha256OfBefore: sha256(before),
+			sha256OfAfter: sha256(after),
+			eventType: frame.type
+		};
+		try {
+			sink?.onDecision(decision);
+		} catch {}
+		return Object.freeze({
+			...frame,
+			payload: next
+		});
+	}
+	return Object.freeze({
+		policy,
+		applyToEvents,
+		patterns,
+		sanitize
+	});
+}
+/**
+* Recursively walks any JSON-shaped value (`null`, primitive, array,
+* object) and applies the supplied transform to every string leaf.
+* Returns a structurally-cloned copy when at least one leaf was
+* rewritten; returns the original input by reference otherwise.
+*/
+function walkAndSanitize(value, transform) {
+	if (typeof value === "string") {
+		const next = transform(value);
+		return next === value ? value : next;
+	}
+	if (Array.isArray(value)) {
+		let mutated = false;
+		const next = new Array(value.length);
+		for (let i = 0; i < value.length; i += 1) {
+			const child = walkAndSanitize(value[i], transform);
+			if (child !== value[i]) mutated = true;
+			next[i] = child;
+		}
+		return mutated ? next : value;
+	}
+	if (value !== null && typeof value === "object") {
+		let mutated = false;
+		const next = {};
+		for (const [key, val] of Object.entries(value)) {
+			const child = walkAndSanitize(val, transform);
+			if (child !== val) mutated = true;
+			next[key] = child;
+		}
+		return mutated ? next : value;
+	}
+	return value;
+}
+function applyToText(text, patterns, policy, open, close) {
+	const segments = splitByWrapEnvelope(text, open, close);
+	const matchedReasons = /* @__PURE__ */ new Set();
+	const next = [];
+	for (const segment of segments) {
+		if (segment.kind === "wrapped") {
+			next.push(segment.text);
+			continue;
+		}
+		let segText = segment.text;
+		for (const pattern of patterns) {
+			const regex = freshRegex(pattern.regex);
+			let didMatch = false;
+			segText = segText.replace(regex, (match) => {
+				didMatch = true;
+				if (policy === "strip") return "";
+				return `${open}${match}${close}`;
+			});
+			if (didMatch) matchedReasons.add(pattern.reason);
+		}
+		next.push(segText);
+	}
+	return {
+		transformed: next.join(""),
+		reasons: [...matchedReasons]
+	};
+}
+function freshRegex(re) {
+	return new RegExp(re.source, re.flags);
+}
+function splitByWrapEnvelope(text, open, close) {
+	const out = [];
+	let cursor = 0;
+	while (cursor < text.length) {
+		const openAt = text.indexOf(open, cursor);
+		if (openAt < 0) {
+			out.push({
+				kind: "plain",
+				text: text.slice(cursor)
+			});
+			break;
+		}
+		if (openAt > cursor) out.push({
+			kind: "plain",
+			text: text.slice(cursor, openAt)
+		});
+		const closeAt = text.indexOf(close, openAt + open.length);
+		if (closeAt < 0) {
+			out.push({
+				kind: "plain",
+				text: text.slice(openAt)
+			});
+			break;
+		}
+		out.push({
+			kind: "wrapped",
+			text: text.slice(openAt, closeAt + close.length)
+		});
+		cursor = closeAt + close.length;
+	}
+	return out;
+}
+function sha256(value) {
+	return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+//#endregion
+export { createDeliveryCommentarySanitizer };
+//# sourceMappingURL=sanitizer.js.map

package/dist/commentary/sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizer.js","names":["policy: DeliveryCommentaryPolicy","applyToEvents: ReadonlyArray<string>","patterns: ReadonlyArray<DeliveryCommentaryPattern>","sink: DeliveryCommentarySink | undefined","decision: DeliveryCommentaryDecision","next: unknown[]","next: Record<string, unknown>","next: string[]","out: { kind: 'plain' | 'wrapped'; text: string }[]"],"sources":["../../src/commentary/sanitizer.ts"],"sourcesContent":["/**\n * Stateless delivery-layer commentary-phase trace sanitizer. Walks\n * outbound `ServerMessage` event frames and applies the configured\n * pattern catalogue to the JSON-stringified payload; matched\n * fragments are wrapped in the configured envelope (default) or\n * stripped (per the `'strip'` policy) or passed through (per the\n * `'pass-through'` policy — operator opt-out for trusted\n * deployments).\n *\n * The sanitizer runs AFTER the `ServerMessage` Zod-validation pass\n * in `@graphorin/protocol` and BEFORE the message hits the wire (so\n * the protocol schema is unchanged; the sanitization is a pure\n * transform applied to validated payloads). It is bytes-equal across\n * the WS / SSE / REST transports — the same input + same policy\n * produces the same output regardless of which transport invoked\n * the sanitizer.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\nimport type { ServerEventFrame } from '@graphorin/protocol';\n\nimport {\n  DEFAULT_APPLY_TO_EVENTS,\n  DEFAULT_DELIVERY_COMMENTARY_PATTERNS,\n} from './built-in-patterns.js';\nimport type {\n  DeliveryCommentaryConfig,\n  DeliveryCommentaryDecision,\n  DeliveryCommentaryPattern,\n  DeliveryCommentaryPolicy,\n  DeliveryCommentaryReason,\n  DeliveryCommentarySink,\n  DeliveryCommentaryTransport,\n} from './types.js';\n\nconst DEFAULT_OPEN = '<<<commentary>>>';\nconst DEFAULT_CLOSE = '<<</commentary>>>';\n\n/**\n * Public surface returned by {@link createDeliveryCommentarySanitizer}.\n *\n * @stable\n */\nexport interface DeliveryCommentarySanitizer {\n  readonly policy: DeliveryCommentaryPolicy;\n  readonly applyToEvents: ReadonlyArray<string>;\n  readonly patterns: ReadonlyArray<DeliveryCommentaryPattern>;\n  /**\n   * Sanitize the payload of a single `event` frame. Returns the\n   * (possibly-replaced) frame; emits an audit decision via the\n   * configured sink when the sanitizer mutated the payload.\n   *\n   * The frame is returned unchanged when:\n   *   - the policy is `'pass-through'`,\n   *   - the event type is not in `applyToEvents`,\n   *   - or no pattern matched the JSON-stringified payload.\n   */\n  sanitize(frame: ServerEventFrame, transport: DeliveryCommentaryTransport): ServerEventFrame;\n}\n\n/**\n * Build a stateless delivery-layer sanitizer. Tests can swap the\n * `sink` for an in-memory recorder; production wires the\n * `@graphorin/security/audit` `appendAudit` helper.\n *\n * @stable\n */\nexport function createDeliveryCommentarySanitizer(\n  config: DeliveryCommentaryConfig = {},\n): DeliveryCommentarySanitizer {\n  const policy: DeliveryCommentaryPolicy = config.policy ?? 'wrap';\n  const applyToEvents: ReadonlyArray<string> = config.applyToEvents ?? DEFAULT_APPLY_TO_EVENTS;\n  const applyToSet = new Set(applyToEvents);\n  const patterns: ReadonlyArray<DeliveryCommentaryPattern> =\n    config.patterns ?? DEFAULT_DELIVERY_COMMENTARY_PATTERNS;\n  const open = config.wrapOpen ?? DEFAULT_OPEN;\n  const close = config.wrapClose ?? DEFAULT_CLOSE;\n  const sink: DeliveryCommentarySink | undefined = config.sink;\n\n  function sanitize(\n    frame: ServerEventFrame,\n    transport: DeliveryCommentaryTransport,\n  ): ServerEventFrame {\n    if (policy === 'pass-through') return frame;\n    if (!applyToSet.has(frame.type)) return frame;\n    const before = JSON.stringify(frame.payload ?? null);\n    const allReasons = new Set<DeliveryCommentaryReason>();\n    let mutated = false;\n    const next = walkAndSanitize(frame.payload, (text) => {\n      const out = applyToText(text, patterns, policy, open, close);\n      for (const reason of out.reasons) allReasons.add(reason);\n      if (out.transformed !== text) mutated = true;\n      return out.transformed;\n    });\n    if (!mutated) return frame;\n    const after = JSON.stringify(next ?? null);\n    const decision: DeliveryCommentaryDecision = {\n      transport,\n      boundary: 'event-emission',\n      policy,\n      applied: true,\n      reasons: [...allReasons],\n      matchedPattern: [...allReasons][0],\n      sha256OfBefore: sha256(before),\n      sha256OfAfter: sha256(after),\n      eventType: frame.type,\n    };\n    try {\n      sink?.onDecision(decision);\n    } catch {\n      // Sink errors must never block the wire — swallow + continue.\n    }\n    return Object.freeze({ ...frame, payload: next });\n  }\n\n  return Object.freeze({\n    policy,\n    applyToEvents,\n    patterns,\n    sanitize,\n  });\n}\n\ninterface ApplyResult {\n  readonly transformed: string;\n  readonly reasons: ReadonlyArray<DeliveryCommentaryReason>;\n}\n\n/**\n * Recursively walks any JSON-shaped value (`null`, primitive, array,\n * object) and applies the supplied transform to every string leaf.\n * Returns a structurally-cloned copy when at least one leaf was\n * rewritten; returns the original input by reference otherwise.\n */\nfunction walkAndSanitize(value: unknown, transform: (s: string) => string): unknown {\n  if (typeof value === 'string') {\n    const next = transform(value);\n    return next === value ? value : next;\n  }\n  if (Array.isArray(value)) {\n    let mutated = false;\n    const next: unknown[] = new Array(value.length);\n    for (let i = 0; i < value.length; i += 1) {\n      const child = walkAndSanitize(value[i], transform);\n      if (child !== value[i]) mutated = true;\n      next[i] = child;\n    }\n    return mutated ? next : value;\n  }\n  if (value !== null && typeof value === 'object') {\n    let mutated = false;\n    const next: Record<string, unknown> = {};\n    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {\n      const child = walkAndSanitize(val, transform);\n      if (child !== val) mutated = true;\n      next[key] = child;\n    }\n    return mutated ? next : value;\n  }\n  return value;\n}\n\nfunction applyToText(\n  text: string,\n  patterns: ReadonlyArray<DeliveryCommentaryPattern>,\n  policy: DeliveryCommentaryPolicy,\n  open: string,\n  close: string,\n): ApplyResult {\n  // Split the body into already-wrapped + plain segments so we never\n  // re-scan inside an existing wrap envelope. This makes the sanitizer\n  // idempotent on the same payload (a second pass produces bytes-equal\n  // output, satisfying the cross-cut composition contract with\n  // Phase 11 session-output sanitization + Phase 11 replay\n  // sanitization).\n  const segments = splitByWrapEnvelope(text, open, close);\n  const matchedReasons = new Set<DeliveryCommentaryReason>();\n  const next: string[] = [];\n  for (const segment of segments) {\n    if (segment.kind === 'wrapped') {\n      next.push(segment.text);\n      continue;\n    }\n    let segText = segment.text;\n    for (const pattern of patterns) {\n      const regex = freshRegex(pattern.regex);\n      let didMatch = false;\n      segText = segText.replace(regex, (match) => {\n        didMatch = true;\n        if (policy === 'strip') return '';\n        return `${open}${match}${close}`;\n      });\n      if (didMatch) matchedReasons.add(pattern.reason);\n    }\n    next.push(segText);\n  }\n  return {\n    transformed: next.join(''),\n    reasons: [...matchedReasons],\n  };\n}\n\nfunction freshRegex(re: RegExp): RegExp {\n  return new RegExp(re.source, re.flags);\n}\n\nfunction splitByWrapEnvelope(\n  text: string,\n  open: string,\n  close: string,\n): ReadonlyArray<{ readonly kind: 'plain' | 'wrapped'; readonly text: string }> {\n  const out: { kind: 'plain' | 'wrapped'; text: string }[] = [];\n  let cursor = 0;\n  while (cursor < text.length) {\n    const openAt = text.indexOf(open, cursor);\n    if (openAt < 0) {\n      out.push({ kind: 'plain', text: text.slice(cursor) });\n      break;\n    }\n    if (openAt > cursor) {\n      out.push({ kind: 'plain', text: text.slice(cursor, openAt) });\n    }\n    const closeAt = text.indexOf(close, openAt + open.length);\n    if (closeAt < 0) {\n      out.push({ kind: 'plain', text: text.slice(openAt) });\n      break;\n    }\n    out.push({ kind: 'wrapped', text: text.slice(openAt, closeAt + close.length) });\n    cursor = closeAt + close.length;\n  }\n  return out;\n}\n\nfunction sha256(value: string): string {\n  return createHash('sha256').update(value, 'utf8').digest('hex');\n}\n"],"mappings":"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"}

package/dist/commentary/types.d.ts

@@ -0,0 +1,120 @@
+//#region src/commentary/types.d.ts
+/**
+ * Types for the delivery-layer commentary-phase trace sanitization
+ * applied by the WebSocket dispatcher (`@graphorin/server/ws`) and
+ * the SSE event-emission boundary (`@graphorin/server/sse`).
+ *
+ * The catalogue + per-policy enum + audit row shape is intentionally
+ * structural so the server's delivery layer stays self-contained. A
+ * deployment that wants to share patterns with the session-output
+ * boundary in `@graphorin/sessions` can pass that package's
+ * `BUILT_IN_COMMENTARY_PATTERNS` through {@link DeliveryCommentaryConfig}.patterns;
+ * the shape is bytes-equal across the two layers (the
+ * defense-in-depth posture is the load-bearing property — see
+ * Phase 11 sanitizer for the storage-write boundary, this module
+ * for the wire-emission boundary).
+ *
+ * @packageDocumentation
+ */
+/**
+ * Operator-facing policy. Identical semantics to the session-output
+ * sanitizer in `@graphorin/sessions/commentary` so the two layers
+ * are bytes-equal on idempotent re-application.
+ *
+ *  - `'wrap'` (default) — wraps the matched fragment in a
+ *    `<<<commentary>>>...<<</commentary>>>` envelope so downstream
+ *    consumers can choose to render or hide based on context.
+ *  - `'strip'` — removes the matched fragment entirely.
+ *  - `'pass-through'` — disables the sanitization (operator opt-in
+ *    for trusted deployments).
+ *
+ * @stable
+ */
+type DeliveryCommentaryPolicy = 'wrap' | 'strip' | 'pass-through';
+/**
+ * Discriminator surfaced on audit rows + counter labels for the
+ * transport that produced the sanitization decision. The cardinality
+ * is bounded (3-valued).
+ *
+ * @stable
+ */
+type DeliveryCommentaryTransport = 'ws' | 'sse' | 'rest';
+/**
+ * Stable label for each detection pattern. Surfaced in the audit row
+ * + the counter label cardinality is bounded.
+ *
+ * @stable
+ */
+type DeliveryCommentaryReason = 'tool.call.start-payload-signature' | 'tool.call.delta-payload-signature' | 'tool.call.end-payload-signature' | 'tool.execute.end-payload-signature' | 'agent.fanout-event-signature' | 'context.compacted-event-signature' | 'agent.model.fellback-event-signature';
+/**
+ * Single pattern entry in the {@link DEFAULT_DELIVERY_COMMENTARY_PATTERNS}
+ * catalogue. The `regex` is matched against the JSON payload of the
+ * `event` frame (after `JSON.stringify(payload)`); deployments that
+ * want to match against the wire-format string instead can supply
+ * their own catalogue.
+ *
+ * @stable
+ */
+interface DeliveryCommentaryPattern {
+  readonly reason: DeliveryCommentaryReason;
+  readonly regex: RegExp;
+  readonly description: string;
+}
+/**
+ * Per-emission decision recorded by the sanitizer. Mirrored on the
+ * audit row + the counter increment.
+ *
+ * @stable
+ */
+interface DeliveryCommentaryDecision {
+  readonly transport: DeliveryCommentaryTransport;
+  readonly boundary: 'event-emission';
+  readonly policy: DeliveryCommentaryPolicy;
+  readonly applied: boolean;
+  readonly reasons: ReadonlyArray<DeliveryCommentaryReason>;
+  readonly matchedPattern: string | undefined;
+  readonly sha256OfBefore: string;
+  readonly sha256OfAfter: string;
+  readonly eventType: string;
+}
+/**
+ * Single audit + counter sink consumed by the sanitizer when a
+ * decision fires. Wiring is optional — operators that do not need
+ * audit telemetry can skip the sink and the sanitizer becomes a
+ * pure transform.
+ *
+ * @stable
+ */
+interface DeliveryCommentarySink {
+  /**
+   * Called once per applied decision. Implementations should be
+   * non-throwing; the sanitizer wraps the call in `try/catch` so a
+   * misbehaving sink never blocks the wire.
+   */
+  onDecision(decision: DeliveryCommentaryDecision): void;
+}
+/**
+ * Public configuration accepted by the WS / SSE / REST event-
+ * emission sanitizer. Shape mirrors the per-server
+ * `WsConfig.commentarySanitization` field documented in the runtime
+ * spec.
+ *
+ * @stable
+ */
+interface DeliveryCommentaryConfig {
+  readonly policy?: DeliveryCommentaryPolicy;
+  /**
+   * Whitelist of `event.type` literals to sanitize. The default
+   * covers the user-visible commentary surface (`text.delta` plus
+   * the two tool-result variants); operators extend the list as
+   * their UI rendering boundary expands.
+   */
+  readonly applyToEvents?: ReadonlyArray<string>;
+  readonly patterns?: ReadonlyArray<DeliveryCommentaryPattern>;
+  readonly wrapOpen?: string;
+  readonly wrapClose?: string;
+  readonly sink?: DeliveryCommentarySink;
+}
+//#endregion
+export { DeliveryCommentaryConfig, DeliveryCommentaryDecision, DeliveryCommentaryPattern, DeliveryCommentaryPolicy, DeliveryCommentaryReason, DeliveryCommentarySink, DeliveryCommentaryTransport };
+//# sourceMappingURL=types.d.ts.map

package/dist/commentary/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/commentary/types.ts"],"sourcesContent":[],"mappings":";;AAgCA;AASA;AAQA;AAkBA;AAYA;;;;;;AAoBA;AAiBA;;;;;;;;;;;;;;;;;;;KApFY,wBAAA;;;;;;;;KASA,2BAAA;;;;;;;KAQA,wBAAA;;;;;;;;;;UAkBK,yBAAA;mBACE;kBACD;;;;;;;;;UAUD,0BAAA;sBACK;;mBAEH;;oBAEC,cAAc;;;;;;;;;;;;;;UAejB,sBAAA;;;;;;uBAMM;;;;;;;;;;UAWN,wBAAA;oBACG;;;;;;;2BAOO;sBACL,cAAc;;;kBAGlB"}