@graphorin/server 0.6.1 → 0.7.0

package/src/commentary/sanitizer.ts

@@ -0,0 +1,238 @@
+/**
+ * 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
+ */
+
+import { createHash } from 'node:crypto';
+import type { ServerEventFrame } from '@graphorin/protocol';
+
+import {
+  DEFAULT_APPLY_TO_EVENTS,
+  DEFAULT_DELIVERY_COMMENTARY_PATTERNS,
+} from './built-in-patterns.js';
+import type {
+  DeliveryCommentaryConfig,
+  DeliveryCommentaryDecision,
+  DeliveryCommentaryPattern,
+  DeliveryCommentaryPolicy,
+  DeliveryCommentaryReason,
+  DeliveryCommentarySink,
+  DeliveryCommentaryTransport,
+} from './types.js';
+
+const DEFAULT_OPEN = '<<<commentary>>>';
+const DEFAULT_CLOSE = '<<</commentary>>>';
+
+/**
+ * Public surface returned by {@link createDeliveryCommentarySanitizer}.
+ *
+ * @stable
+ */
+export interface DeliveryCommentarySanitizer {
+  readonly policy: DeliveryCommentaryPolicy;
+  readonly applyToEvents: ReadonlyArray<string>;
+  readonly patterns: ReadonlyArray<DeliveryCommentaryPattern>;
+  /**
+   * Sanitize the payload of a single `event` frame. Returns the
+   * (possibly-replaced) frame; emits an audit decision via the
+   * configured sink when the sanitizer mutated the payload.
+   *
+   * The frame is returned unchanged when:
+   *   - the policy is `'pass-through'`,
+   *   - the event type is not in `applyToEvents`,
+   *   - or no pattern matched the JSON-stringified payload.
+   */
+  sanitize(frame: ServerEventFrame, transport: DeliveryCommentaryTransport): ServerEventFrame;
+}
+
+/**
+ * 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
+ */
+export function createDeliveryCommentarySanitizer(
+  config: DeliveryCommentaryConfig = {},
+): DeliveryCommentarySanitizer {
+  const policy: DeliveryCommentaryPolicy = config.policy ?? 'wrap';
+  const applyToEvents: ReadonlyArray<string> = config.applyToEvents ?? DEFAULT_APPLY_TO_EVENTS;
+  const applyToSet = new Set(applyToEvents);
+  const patterns: ReadonlyArray<DeliveryCommentaryPattern> =
+    config.patterns ?? DEFAULT_DELIVERY_COMMENTARY_PATTERNS;
+  const open = config.wrapOpen ?? DEFAULT_OPEN;
+  const close = config.wrapClose ?? DEFAULT_CLOSE;
+  const sink: DeliveryCommentarySink | undefined = config.sink;
+
+  function sanitize(
+    frame: ServerEventFrame,
+    transport: DeliveryCommentaryTransport,
+  ): ServerEventFrame {
+    if (policy === 'pass-through') return frame;
+    if (!applyToSet.has(frame.type)) return frame;
+    const before = JSON.stringify(frame.payload ?? null);
+    const allReasons = new Set<DeliveryCommentaryReason>();
+    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: DeliveryCommentaryDecision = {
+      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 {
+      // Sink errors must never block the wire - swallow + continue.
+    }
+    return Object.freeze({ ...frame, payload: next });
+  }
+
+  return Object.freeze({
+    policy,
+    applyToEvents,
+    patterns,
+    sanitize,
+  });
+}
+
+interface ApplyResult {
+  readonly transformed: string;
+  readonly reasons: ReadonlyArray<DeliveryCommentaryReason>;
+}
+
+/**
+ * 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: unknown, transform: (s: string) => string): unknown {
+  if (typeof value === 'string') {
+    const next = transform(value);
+    return next === value ? value : next;
+  }
+  if (Array.isArray(value)) {
+    let mutated = false;
+    const next: unknown[] = 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: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      const child = walkAndSanitize(val, transform);
+      if (child !== val) mutated = true;
+      next[key] = child;
+    }
+    return mutated ? next : value;
+  }
+  return value;
+}
+
+function applyToText(
+  text: string,
+  patterns: ReadonlyArray<DeliveryCommentaryPattern>,
+  policy: DeliveryCommentaryPolicy,
+  open: string,
+  close: string,
+): ApplyResult {
+  // Split the body into already-wrapped + plain segments so we never
+  // re-scan inside an existing wrap envelope. This makes the sanitizer
+  // idempotent on the same payload (a second pass produces bytes-equal
+  // output, satisfying the cross-cut composition contract with
+  // Phase 11 session-output sanitization + Phase 11 replay
+  // sanitization).
+  const segments = splitByWrapEnvelope(text, open, close);
+  const matchedReasons = new Set<DeliveryCommentaryReason>();
+  const next: string[] = [];
+  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: RegExp): RegExp {
+  return new RegExp(re.source, re.flags);
+}
+
+function splitByWrapEnvelope(
+  text: string,
+  open: string,
+  close: string,
+): ReadonlyArray<{ readonly kind: 'plain' | 'wrapped'; readonly text: string }> {
+  const out: { kind: 'plain' | 'wrapped'; text: string }[] = [];
+  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: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}

package/src/commentary/types.ts

@@ -0,0 +1,130 @@
+/**
+ * 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
+ */
+export 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
+ */
+export type DeliveryCommentaryTransport = 'ws' | 'sse' | 'rest';
+
+/**
+ * Stable label for each detection pattern. Surfaced in the audit row
+ * + the counter label cardinality is bounded.
+ *
+ * @stable
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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;
+}