@od-oneapp/ai-platform 0.1.0

package/src/tools/compliance/create-compliant-stream.ts

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview Compliant Streaming Wrapper
+ * Compliant Streaming Wrapper
+ * Drop-in replacement for createDataStreamResponse with compliance features
+ */
+
+// Note: createDataStreamResponse API changed in AI SDK v6
+// This module provides helpers for compliance logging during streaming
+import { getAuditLogger } from '../../governance/audit/audit-logger';
+import { redactPHI } from '../../governance/compliance/validators/redaction-utils';
+
+import type { RedactionStrategy } from '../../governance/compliance/types';
+import type { DataStreamWriter } from '../../streaming/core/protocol';
+
+// Define POLICY_VERSION locally since it doesn't exist in config
+const POLICY_VERSION = '1.0.0';
+
+/**
+ * Options for compliant streaming
+ */
+interface CompliantStreamOptions {
+  dataStream: DataStreamWriter;
+  execute: (dataStream: DataStreamWriter) => Promise<void>;
+  complianceOptions: {
+    enablePHIRedaction?: boolean;
+    enableABAC?: boolean;
+    policyVersion?: string;
+    auditLogger?: ReturnType<typeof getAuditLogger>;
+    abacContext?: { actor: { id: string } };
+    redactionStrategy?: RedactionStrategy;
+  };
+  onError?: (error: Error) => void;
+  enableAuditLogging?: boolean;
+}
+
+/**
+ * Create a compliant data stream response
+ * Wraps Vercel AI SDK v6's createDataStreamResponse with compliance features
+ *
+ * @param options - Stream configuration with compliance
+ * @returns Response object with compliant streaming
+ *
+ * @example
+ * ```ts
+ * export async function POST(req: Request) {
+ *   const { messages } = await req.json();
+ *
+ *   return createCompliantStream({
+ *     execute: async (dataStream) => {
+ *       const result = streamText({
+ *         model: complianceModel,
+ *         messages,
+ *       });
+ *       result.mergeIntoDataStream(dataStream);
+ *     },
+ *     complianceOptions: {
+ *       enablePHIRedaction: true,
+ *       enableABAC: false,
+ *       policyVersion: 'v2.0',
+ *     },
+ *   });
+ * }
+ * ```
+ */
+export async function createCompliantStream(options: CompliantStreamOptions): Promise<void> {
+  const { dataStream, execute, complianceOptions, onError } = options;
+  const logger = complianceOptions.auditLogger ?? getAuditLogger();
+  const startTime = Date.now();
+
+  try {
+    // Execute the user's stream logic
+    await execute(dataStream);
+
+    // Log successful stream completion
+    await logger.log({
+      actor: complianceOptions.abacContext?.actor.id || 'system',
+      action: 'generation',
+      input_hash: 'stream',
+      output_snapshot: {
+        streamCompleted: true,
+        durationMs: Date.now() - startTime,
+      },
+      policy_version: complianceOptions.policyVersion ?? POLICY_VERSION,
+      metadata: {
+        phiRedaction: complianceOptions.enablePHIRedaction,
+        abacEnabled: complianceOptions.enableABAC,
+      },
+    });
+  } catch (error) {
+    // Log stream error
+    await logger.log({
+      actor: complianceOptions.abacContext?.actor.id || 'system',
+      action: 'generation',
+      input_hash: 'stream',
+      output_snapshot: {
+        error: error instanceof Error ? error.message : 'Unknown error',
+        durationMs: Date.now() - startTime,
+      },
+      policy_version: complianceOptions.policyVersion ?? POLICY_VERSION,
+      metadata: {
+        failed: true,
+      },
+    });
+
+    // Call error handler if provided
+    if (onError) {
+      onError(error instanceof Error ? error : new Error(String(error)));
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Create a compliant stream with automatic PHI redaction in chunks
+ * Note: For real-time PHI redaction, use wrapWithCompliance on the model instead
+ */
+export async function createCompliantStreamWithRedaction(
+  options: CompliantStreamOptions & {
+    minConfidence?: number;
+  },
+): Promise<void> {
+  const minConfidence = options.minConfidence ?? 0.6;
+
+  const redactionEnabled = options.complianceOptions.enablePHIRedaction ?? true;
+  const redactingStream = redactionEnabled
+    ? {
+        write(data: unknown) {
+          if (data && typeof data === 'object' && 'type' in data) {
+            const payload = data as { type?: unknown; data?: unknown };
+            if (payload.type === 'textDelta' && typeof payload.data === 'string') {
+              const { redacted } = redactPHI(
+                payload.data,
+                options.complianceOptions.redactionStrategy,
+                {
+                  minConfidence,
+                },
+              );
+              options.dataStream.write({ ...payload, data: redacted });
+              return;
+            }
+
+            if (
+              payload.type === 'codeDelta' &&
+              payload.data &&
+              typeof payload.data === 'object' &&
+              'code' in (payload.data as { code?: unknown })
+            ) {
+              const codeValue = (payload.data as { code?: unknown }).code;
+              if (typeof codeValue === 'string') {
+                const { redacted } = redactPHI(
+                  codeValue,
+                  options.complianceOptions.redactionStrategy,
+                  {
+                    minConfidence,
+                  },
+                );
+                options.dataStream.write({
+                  ...payload,
+                  data: { ...(payload.data as Record<string, unknown>), code: redacted },
+                });
+                return;
+              }
+            }
+          }
+
+          options.dataStream.write(data);
+        },
+      }
+    : options.dataStream;
+
+  return createCompliantStream({
+    ...options,
+    dataStream: redactingStream,
+  });
+}
+
+/**
+ * Simplified helper for creating stream loggers
+ */
+export function createCompliantStreamSimple(
+  actorId: string = 'anonymous',
+  enableRedaction: boolean = true,
+): {
+  logStart: () => number;
+  logCompletion: (startTime: number) => Promise<void>;
+  logError: (startTime: number, error: Error) => Promise<void>;
+} {
+  const logger = getAuditLogger();
+
+  return {
+    logStart: () => Date.now(),
+
+    logCompletion: async (startTime: number) => {
+      await logger.log({
+        actor: actorId,
+        action: 'generation',
+        input_hash: 'stream',
+        output_snapshot: {
+          completed: true,
+          durationMs: Date.now() - startTime,
+        },
+        policy_version: POLICY_VERSION,
+        metadata: {
+          redactionEnabled: enableRedaction,
+        },
+      });
+    },
+
+    logError: async (startTime: number, error: Error) => {
+      await logger.log({
+        actor: actorId,
+        action: 'generation',
+        input_hash: 'stream',
+        output_snapshot: {
+          error: error.message,
+          durationMs: Date.now() - startTime,
+        },
+        policy_version: POLICY_VERSION,
+        metadata: {
+          redactionEnabled: enableRedaction,
+        },
+      });
+    },
+  };
+}

package/src/tools/compliance/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Tool compliance wrappers: ABAC, approval, timeout, retry patterns.
+ * @module @od-oneapp/ai-platform/tools/compliance
+ */
+
+export * from './tool-wrapper';
+export * from './compliance-wrapper';
+export * from './create-compliant-stream';

package/src/tools/compliance/phi-redaction.ts

@@ -0,0 +1,406 @@
+/**
+ * @fileoverview PHI Redaction Utilities
+ * Pure utility functions for redacting Protected Health Information (PHI)
+ * from language model prompts, results, and streams.
+ *
+ * Extracted from compliance-wrapper.ts for modularity.
+ */
+
+import { redactPHI } from '../../governance/compliance/validators/redaction-utils';
+
+import type { ComplianceOptions, PHIDetection } from '../../governance/compliance/types';
+import type {
+  SDKLanguageModelV3Content as LanguageModelV3Content,
+  SDKLanguageModelV3GenerateResult as LanguageModelV3GenerateResult,
+  SDKLanguageModelV3Message as LanguageModelV3Message,
+  SDKLanguageModelV3Prompt as LanguageModelV3Prompt,
+  SDKLanguageModelV3StreamPart as LanguageModelV3StreamPart,
+  SDKLanguageModelV3ToolResult as LanguageModelV3ToolResult,
+  SDKLanguageModelV3ToolResultOutput as LanguageModelV3ToolResultOutput,
+} from '../../shared';
+
+/**
+ * Type guard for plain objects (records).
+ */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Redact PHI from a single string value, collecting detections.
+ */
+export const redactStringValue = (
+  text: string,
+  strategy: ComplianceOptions['redactionStrategy'],
+  detections: PHIDetection[],
+  minConfidence: number,
+): string => {
+  const { redacted, detections: found } = redactPHI(text, strategy, { minConfidence });
+  detections.push(...found);
+  return redacted;
+};
+
+/**
+ * Recursively redact PHI from an unknown value (string, array, or object).
+ */
+export const redactUnknownValue = (
+  value: unknown,
+  strategy: ComplianceOptions['redactionStrategy'],
+  detections: PHIDetection[],
+  minConfidence: number,
+): unknown => {
+  if (typeof value === 'string') {
+    return redactStringValue(value, strategy, detections, minConfidence);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(entry => redactUnknownValue(entry, strategy, detections, minConfidence));
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        redactUnknownValue(entry, strategy, detections, minConfidence),
+      ]),
+    );
+  }
+
+  return value;
+};
+
+/**
+ * Redact PHI from a tool result output (text or JSON).
+ */
+export const redactToolResultOutput = (
+  output: LanguageModelV3ToolResultOutput,
+  strategy: ComplianceOptions['redactionStrategy'],
+  detections: PHIDetection[],
+  minConfidence: number,
+): LanguageModelV3ToolResultOutput => {
+  if (output.type === 'text') {
+    return {
+      type: 'text',
+      value: redactStringValue(output.value, strategy, detections, minConfidence),
+      providerOptions: output.providerOptions,
+    };
+  }
+
+  if (output.type === 'json') {
+    return {
+      type: 'json',
+      value: redactUnknownValue(output.value, strategy, detections, minConfidence) as NonNullable<
+        typeof output.value
+      >,
+      providerOptions: output.providerOptions,
+    };
+  }
+
+  return output;
+};
+
+/**
+ * Redact PHI from a full prompt (array of messages).
+ *
+ * Processes system, user, assistant, and tool messages, redacting
+ * text content, tool call inputs, and tool result outputs.
+ */
+export const redactPrompt = (
+  prompt: LanguageModelV3Prompt,
+  options: ComplianceOptions,
+): { prompt: LanguageModelV3Prompt; detections: PHIDetection[] } => {
+  const detections: PHIDetection[] = [];
+  const strategy = options.redactionStrategy ?? 'MASK';
+
+  const processedPrompt = prompt.map(message => {
+    if (message.role === 'system') {
+      return {
+        ...message,
+        content: redactStringValue(message.content, strategy, detections, 0.6),
+      } satisfies LanguageModelV3Message;
+    }
+
+    if (message.role === 'user') {
+      const parts = Array.isArray(message.content) ? message.content : [];
+      const redactedParts = parts.map(part => {
+        if (part.type === 'text') {
+          return {
+            ...part,
+            text: redactStringValue(part.text, strategy, detections, 0.6),
+          };
+        }
+        return part;
+      });
+      return {
+        ...message,
+        content: redactedParts,
+      } satisfies LanguageModelV3Message;
+    }
+
+    if (message.role === 'assistant') {
+      const parts = Array.isArray(message.content) ? message.content : [];
+      const redactedParts = parts.map(part => {
+        if (part.type === 'text' || part.type === 'reasoning') {
+          return {
+            ...part,
+            text: redactStringValue(part.text, strategy, detections, 0.6),
+          };
+        }
+
+        if (part.type === 'tool-result') {
+          return {
+            ...part,
+            output: redactToolResultOutput(part.output, strategy, detections, 0.6),
+          };
+        }
+
+        if (part.type === 'tool-call') {
+          const inputValue = part.input;
+          if (typeof inputValue === 'string') {
+            let redactedInput = inputValue;
+            try {
+              const parsed = JSON.parse(inputValue) as unknown;
+              const redacted = redactUnknownValue(parsed, strategy, detections, 0.6);
+              redactedInput = JSON.stringify(redacted);
+            } catch {
+              redactedInput = redactStringValue(inputValue, strategy, detections, 0.6);
+            }
+            return { ...part, input: redactedInput };
+          }
+
+          const redactedInput = redactUnknownValue(inputValue, strategy, detections, 0.6);
+          return { ...part, input: redactedInput };
+        }
+
+        return part;
+      });
+      return {
+        ...message,
+        content: redactedParts,
+      } satisfies LanguageModelV3Message;
+    }
+
+    if (message.role === 'tool') {
+      const parts = Array.isArray(message.content) ? message.content : [];
+      const redactedParts = parts.map(part => {
+        if (part.type === 'tool-result') {
+          return {
+            ...part,
+            output: redactToolResultOutput(part.output, strategy, detections, 0.6),
+          };
+        }
+        return part;
+      });
+      return {
+        ...message,
+        content: redactedParts,
+      } satisfies LanguageModelV3Message;
+    }
+
+    return message;
+  });
+
+  return { prompt: processedPrompt, detections };
+};
+
+/**
+ * Redact PHI from a generate result (text, reasoning, and tool results).
+ */
+export const redactGenerateResult = (
+  result: LanguageModelV3GenerateResult,
+  options: ComplianceOptions,
+): { result: LanguageModelV3GenerateResult; detections: PHIDetection[] } => {
+  const detections: PHIDetection[] = [];
+  const strategy = options.redactionStrategy ?? 'MASK';
+
+  const content = result.content.map(part => {
+    if (part.type === 'text' || part.type === 'reasoning') {
+      return {
+        ...part,
+        text: redactStringValue(part.text, strategy, detections, 0.7),
+      };
+    }
+
+    if (part.type === 'tool-result') {
+      const toolResult = part;
+      const redactedResult = redactUnknownValue(toolResult.result, strategy, detections, 0.7);
+      return { ...toolResult, result: redactedResult as LanguageModelV3ToolResult['result'] };
+    }
+
+    return part;
+  });
+
+  return {
+    result: {
+      ...result,
+      content: content as LanguageModelV3Content[],
+    },
+    detections,
+  };
+};
+
+/**
+ * Create a TransformStream that redacts PHI from streaming language model output.
+ *
+ * Buffers text/reasoning/tool-input deltas to avoid splitting PHI patterns
+ * across chunk boundaries, then flushes remaining content on stream end.
+ *
+ * @param options - Compliance configuration
+ * @param onDetections - Callback invoked with all detections when the stream completes
+ */
+export const createComplianceStreamTransform = (
+  options: ComplianceOptions,
+  onDetections: (detections: PHIDetection[]) => Promise<void>,
+): TransformStream<LanguageModelV3StreamPart, LanguageModelV3StreamPart> => {
+  const detections: PHIDetection[] = [];
+  const strategy = options.redactionStrategy ?? 'MASK';
+  const holdBackSize = 64;
+  const buffers = new Map<string, { pending: string; deltaType: string }>();
+
+  const extractDelta = (part: LanguageModelV3StreamPart): string | null => {
+    if (
+      part.type === 'text-delta' ||
+      part.type === 'reasoning-delta' ||
+      part.type === 'tool-input-delta'
+    ) {
+      return part.delta;
+    }
+    return null;
+  };
+
+  const getKey = (part: LanguageModelV3StreamPart): string | null => {
+    if (
+      part.type === 'text-delta' ||
+      part.type === 'reasoning-delta' ||
+      part.type === 'tool-input-delta'
+    ) {
+      return `${part.type}:${part.id}`;
+    }
+    if (
+      part.type === 'text-end' ||
+      part.type === 'reasoning-end' ||
+      part.type === 'tool-input-end'
+    ) {
+      const deltaType = part.type.replace('-end', '-delta');
+      return `${deltaType}:${part.id}`;
+    }
+    if (
+      part.type === 'text-start' ||
+      part.type === 'reasoning-start' ||
+      part.type === 'tool-input-start'
+    ) {
+      const deltaType = part.type.replace('-start', '-delta');
+      return `${deltaType}:${part.id}`;
+    }
+    return null;
+  };
+
+  const getDeltaType = (part: LanguageModelV3StreamPart): string | null => {
+    if (
+      part.type === 'text-delta' ||
+      part.type === 'reasoning-delta' ||
+      part.type === 'tool-input-delta'
+    ) {
+      return part.type;
+    }
+    if (
+      part.type === 'text-start' ||
+      part.type === 'reasoning-start' ||
+      part.type === 'tool-input-start'
+    ) {
+      return part.type.replace('-start', '-delta');
+    }
+    if (
+      part.type === 'text-end' ||
+      part.type === 'reasoning-end' ||
+      part.type === 'tool-input-end'
+    ) {
+      return part.type.replace('-end', '-delta');
+    }
+    return null;
+  };
+
+  return new TransformStream<LanguageModelV3StreamPart, LanguageModelV3StreamPart>({
+    transform(part, controller) {
+      const delta = extractDelta(part);
+      const key = getKey(part);
+      const deltaType = getDeltaType(part);
+
+      if (delta && key && deltaType) {
+        const state = buffers.get(key) ?? { pending: '', deltaType };
+        const pending = state.pending + delta;
+
+        if (pending.length <= holdBackSize) {
+          buffers.set(key, { ...state, pending });
+          return;
+        }
+
+        const safePrefix = pending.slice(0, pending.length - holdBackSize);
+        const redactedPrefix = redactStringValue(safePrefix, strategy, detections, 0.7);
+        buffers.set(key, { ...state, pending: pending.slice(pending.length - holdBackSize) });
+
+        if (redactedPrefix.length > 0) {
+          controller.enqueue({
+            ...part,
+            delta: redactedPrefix,
+          } as LanguageModelV3StreamPart);
+        }
+        return;
+      }
+
+      if (
+        part.type === 'text-end' ||
+        part.type === 'reasoning-end' ||
+        part.type === 'tool-input-end'
+      ) {
+        if (key) {
+          const state = buffers.get(key);
+          if (state && state.pending.length > 0) {
+            const redactedTail = redactStringValue(state.pending, strategy, detections, 0.7);
+            if (redactedTail.length > 0 && deltaType) {
+              controller.enqueue({
+                type: deltaType as LanguageModelV3StreamPart['type'],
+                id: part.id,
+                delta: redactedTail,
+                providerMetadata: 'providerMetadata' in part ? part.providerMetadata : undefined,
+              } as LanguageModelV3StreamPart);
+            }
+          }
+          buffers.delete(key);
+        }
+        controller.enqueue(part);
+        return;
+      }
+
+      if (
+        part.type === 'text-start' ||
+        part.type === 'reasoning-start' ||
+        part.type === 'tool-input-start'
+      ) {
+        if (key && deltaType && !buffers.has(key)) {
+          buffers.set(key, { pending: '', deltaType });
+        }
+        controller.enqueue(part);
+        return;
+      }
+
+      controller.enqueue(part);
+    },
+    async flush(controller) {
+      for (const [key, state] of buffers.entries()) {
+        if (state.pending.length > 0) {
+          const redactedTail = redactStringValue(state.pending, strategy, detections, 0.7);
+          if (redactedTail.length > 0) {
+            controller.enqueue({
+              type: state.deltaType as LanguageModelV3StreamPart['type'],
+              id: key.split(':').slice(1).join(':'),
+              delta: redactedTail,
+            } as LanguageModelV3StreamPart);
+          }
+        }
+      }
+      buffers.clear();
+      await onDetections(detections);
+      controller.terminate();
+    },
+  });
+};