@ai-pip/csl 0.1.0

package/layers/csl/ports/output/Logger.ts

@@ -0,0 +1,17 @@
+
+
+/**
+ * LoggerPort is the port for the logger
+ * 
+ * @property info - Info
+ * @property warn - Warn
+ * @property error - Error
+ * @property debug - Debug
+ */
+
+export interface LoggerPort {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+}

package/layers/csl/ports/output/PolicyRepository.ts

@@ -0,0 +1,29 @@
+import type { PolicyRule } from '../../domain/value-objects';
+
+/**
+ * PolicyRepositoryPort is the port for the policy repository
+ * 
+ * @property getActivePolicy - Get the currently active policy
+ * @property getPolicyByVersion - Get a policy by its version
+ * @property getAllPolicies - Get all available policies
+ */
+export interface PolicyRepositoryPort {
+    /**
+     * Get the currently active policy
+     * @returns The active PolicyRule
+     */
+    getActivePolicy(): Promise<PolicyRule>;
+    
+    /**
+     * Get a policy by its version
+     * @param version - The version of the policy to retrieve
+     * @returns The PolicyRule for the specified version, or null if not found
+     */
+    getPolicyByVersion(version: string): Promise<PolicyRule | null>;
+    
+    /**
+     * Get all available policies
+     * @returns An array of all available PolicyRule instances
+     */
+    getAllPolicies(): Promise<PolicyRule[]>;
+}

package/layers/csl/ports/output/SegmentClassified.ts

@@ -0,0 +1,8 @@
+import type { Origin, TrustLevel } from "../../domain/value-objects";
+
+export interface SegmentClassified {
+    segmentId: string;
+    text: string;
+    origin: Origin;
+    trustLevel: TrustLevel;
+}

package/layers/csl/ports/output/TimeStampProvider.ts

@@ -0,0 +1,5 @@
+
+
+export interface TimeStampProviderPort {
+    now(): number;
+}

package/layers/csl/services/CSLService.ts

@@ -0,0 +1,393 @@
+import type { SegmentationPort } from '../ports/input/SegmentationPort'
+import { CSLResult } from '../domain/entities/CSLResult'
+import type { Segment } from '../domain/entities'
+import { SegmentationError } from '../domain/exceptions'
+import { DOMAdapter } from '../adapters/input/DOMAdapter'
+import {
+  NormalizationService,
+  OriginClassificationService,
+  PiDetectionService,
+  AnomalyService,
+  PolicyService,
+  LineageService,
+} from '../domain/services'
+import type { HashGeneratorPort } from '../ports/output/HashGenerator'
+import type { LoggerPort } from '../ports/output/Logger'
+import type { TimeStampProviderPort } from '../ports/output/TimeStampProvider'
+import { LineageEntry, ContentHash } from '../domain/value-objects'
+
+/**
+ * Configuration for CSLService
+ */
+export interface CSLServiceConfig {
+  readonly enablePolicyValidation?: boolean
+  readonly enableLineageTracking?: boolean
+  readonly hashAlgorithm?: 'sha256' | 'sha512'
+}
+
+/**
+ * CSLService is the main orchestrator service for the Context Segmentation Layer.
+ * 
+ * @remarks
+ * This service implements the SegmentationPort and coordinates the complete CSL processing pipeline.
+ * It orchestrates all domain services, adapters, and output ports to process content from DOM
+ * elements or documents through the full segmentation, classification, and analysis pipeline.
+ * 
+ * **Processing Pipeline:**
+ * 1. Adapts DOM element/document to extract content segments (DOMAdapter)
+ * 2. Normalizes segment content (NormalizationService)
+ * 3. Classifies segments by origin (OriginClassificationService)
+ * 4. Detects prompt injection attempts (PiDetectionService)
+ * 5. Generates cryptographic hashes (HashGeneratorPort)
+ * 6. Calculates anomaly scores (AnomalyService)
+ * 7. Validates against policies (PolicyService, optional)
+ * 8. Tracks lineage for auditability (LineageService)
+ * 9. Aggregates results into CSLResult
+ * 
+ * **Key Features:**
+ * - Complete pipeline orchestration
+ * - Error handling with SegmentationError
+ * - Configurable processing options
+ * - Performance tracking (processing time)
+ * - Comprehensive lineage tracking
+ * 
+ * **Dependencies:**
+ * - Domain Services: Normalization, Classification, PI Detection, Anomaly, Policy, Lineage
+ * - Adapters: DOMAdapter (input)
+ * - Ports: HashGenerator, Logger, TimeStampProvider (output)
+ * 
+ * @example
+ * ```typescript
+ * // Create CSLService with all dependencies
+ * const cslService = new CSLService(
+ *   new DOMAdapter(),
+ *   new OriginClassificationService(),
+ *   new PiDetectionService(),
+ *   new AnomalyService(),
+ *   new PolicyService(policyRepository),
+ *   new LineageService(),
+ *   new CryptoHashGenerator(),
+ *   new ConsoleLogger(),
+ *   new SystemTimestampProvider(),
+ *   { enablePolicyValidation: true }
+ * )
+ * 
+ * // Process a DOM element
+ * const result = await cslService.segment(document.body)
+ * 
+ * // Access results
+ * console.log(`Processed ${result.metadata.total_segments} segments`)
+ * console.log(`Blocked: ${result.getBlockedCount()} segments`)
+ * ```
+ */
+export class CSLService implements SegmentationPort {
+  private readonly config: Required<CSLServiceConfig>
+
+  constructor(
+    private readonly domAdapter: DOMAdapter,
+    private readonly originClassificationService: OriginClassificationService,
+    private readonly piDetectionService: PiDetectionService,
+    private readonly anomalyService: AnomalyService,
+    private readonly policyService: PolicyService,
+    private readonly lineageService: LineageService,
+    private readonly hashGenerator: HashGeneratorPort,
+    private readonly logger: LoggerPort,
+    private readonly timestampProvider: TimeStampProviderPort,
+    config?: CSLServiceConfig
+  ) {
+    // Validate required dependencies
+    if (!domAdapter) {
+      throw new TypeError('CSLService: domAdapter is required')
+    }
+    if (!originClassificationService) {
+      throw new TypeError('CSLService: originClassificationService is required')
+    }
+    if (!piDetectionService) {
+      throw new TypeError('CSLService: piDetectionService is required')
+    }
+    if (!anomalyService) {
+      throw new TypeError('CSLService: anomalyService is required')
+    }
+    if (!policyService) {
+      throw new TypeError('CSLService: policyService is required')
+    }
+    if (!lineageService) {
+      throw new TypeError('CSLService: lineageService is required')
+    }
+    if (!hashGenerator) {
+      throw new TypeError('CSLService: hashGenerator is required')
+    }
+    if (!logger) {
+      throw new TypeError('CSLService: logger is required')
+    }
+    if (!timestampProvider) {
+      throw new TypeError('CSLService: timestampProvider is required')
+    }
+
+    this.config = {
+      enablePolicyValidation: config?.enablePolicyValidation ?? true,
+      enableLineageTracking: config?.enableLineageTracking ?? true,
+      hashAlgorithm: config?.hashAlgorithm ?? 'sha256',
+    }
+  }
+
+  /**
+   * Segments content from a DOM element or document through the CSL processing pipeline.
+   * 
+   * @param element - The HTMLElement or Document to segment
+   * @returns Promise that resolves to CSLResult with all processed segments
+   * @throws {SegmentationError} If segmentation fails
+   * 
+   * @example
+   * ```typescript
+   * const result = await cslService.segment(document.body)
+   * ```
+   */
+  async segment(element: HTMLElement | Document): Promise<CSLResult> {
+    const startTime = this.timestampProvider.now()
+
+    try {
+      this.logger.debug(`CSLService: Starting segmentation for element`)
+
+      // Step 1: Adapt DOM to segments
+      const segments = this.domAdapter.adapt(element)
+      this.logger.debug(`CSLService: Extracted ${segments.length} segments from DOM`)
+
+      if (segments.length === 0) {
+        this.logger.warn('CSLService: No segments extracted from DOM element')
+        return this.createEmptyResult(startTime)
+      }
+
+      // Step 2: Process each segment through the pipeline
+      const processedSegments: Segment[] = []
+      const blockedSegmentIds: string[] = []
+      const allLineageEntries: LineageEntry[] = []
+
+      for (const segment of segments) {
+        try {
+          const processedSegment = await this.processSegment(segment, startTime)
+          processedSegments.push(processedSegment)
+
+          // Track blocked segments
+          if (processedSegment.shouldBlock()) {
+            blockedSegmentIds.push(processedSegment.id)
+            this.logger.warn(`CSLService: Segment ${processedSegment.id} blocked due to security concerns`)
+          }
+
+          // Collect lineage entries
+          if (this.config.enableLineageTracking && processedSegment.lineage) {
+            allLineageEntries.push(...processedSegment.lineage)
+          }
+        } catch (error) {
+          this.logger.error(`CSLService: Error processing segment ${segment.id}: ${error}`)
+          // Continue processing other segments even if one fails
+        }
+      }
+
+      // Step 3: Calculate processing time
+      const processingTime = this.timestampProvider.now() - startTime
+
+      // Step 4: Create CSLResult
+      const result = new CSLResult({
+        segments: processedSegments,
+        metadata: {
+          blocked_segments: blockedSegmentIds,
+          processing_time_ms: processingTime,
+        },
+        lineage: allLineageEntries,
+      })
+
+      this.logger.info(
+        `CSLService: Segmentation completed. Processed ${processedSegments.length} segments in ${processingTime}ms`
+      )
+
+      return result
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error during segmentation'
+      this.logger.error(`CSLService: Segmentation failed: ${errorMessage}`)
+      throw new SegmentationError(`Failed to segment content: ${errorMessage}`, error)
+    }
+  }
+
+  /**
+   * Processes a single segment through the complete pipeline
+   */
+  private async processSegment(segment: Segment, startTime: number): Promise<Segment> {
+    const segmentStartTime = this.timestampProvider.now()
+
+    // Step 1: Normalize content
+    const normalizedContent = this.normalizeSegmentContent(segment)
+
+    // Step 2: Classify origin and assign trust level
+    this.classifySegment(segment)
+
+    // Step 3: Detect prompt injection
+    this.detectPromptInjection(segment, normalizedContent)
+
+    // Step 4: Generate hash
+    await this.generateSegmentHash(segment, normalizedContent)
+
+    // Step 5: Calculate anomaly score
+    this.calculateSegmentAnomalyScore(segment)
+
+    // Step 6: Validate policies (optional)
+    if (this.config.enablePolicyValidation) {
+      await this.validateSegmentPolicy(segment)
+    }
+
+    // Step 7: Add lineage entries to segment
+    if (this.config.enableLineageTracking) {
+      this.addLineageToSegment(segment)
+    }
+
+    const segmentProcessingTime = this.timestampProvider.now() - segmentStartTime
+    this.logger.debug(`CSLService: Processed segment ${segment.id} in ${segmentProcessingTime}ms`)
+
+    return segment
+  }
+
+  /**
+   * Normalizes segment content and tracks lineage
+   */
+  private normalizeSegmentContent(segment: Segment): string {
+    const normalizedContent = NormalizationService.normalize(segment.content)
+
+    if (this.config.enableLineageTracking) {
+      this.lineageService.addEntry(
+        segment.id,
+        new LineageEntry('normalization', this.timestampProvider.now(), 'Content normalized')
+      )
+    }
+
+    return normalizedContent
+  }
+
+  /**
+   * Classifies segment origin and assigns trust level
+   */
+  private classifySegment(segment: Segment): void {
+    const trustLevel = this.originClassificationService.classify(segment.origin)
+    segment.assignTrustLevel(trustLevel)
+
+    if (this.config.enableLineageTracking) {
+      this.lineageService.addEntry(
+        segment.id,
+        new LineageEntry(
+          'classification',
+          this.timestampProvider.now(),
+          `Classified as ${trustLevel.value}`
+        )
+      )
+    }
+  }
+
+  /**
+   * Detects prompt injection in segment
+   */
+  private detectPromptInjection(segment: Segment, normalizedContent: string): void {
+    const piDetection = this.piDetectionService.detect(normalizedContent)
+    segment.assignPiDetection(piDetection)
+
+    if (this.config.enableLineageTracking) {
+      this.lineageService.addEntry(
+        segment.id,
+        new LineageEntry(
+          'pi_detection',
+          this.timestampProvider.now(),
+          `PI detection: ${piDetection.action} (score: ${piDetection.score.toFixed(2)})`
+        )
+      )
+    }
+  }
+
+  /**
+   * Generates hash for segment content
+   */
+  private async generateSegmentHash(segment: Segment, normalizedContent: string): Promise<void> {
+    const hashValue = await this.hashGenerator.generate(normalizedContent, this.config.hashAlgorithm)
+    const contentHash = new ContentHash(hashValue, this.config.hashAlgorithm)
+    segment.assignHash(contentHash)
+
+    if (this.config.enableLineageTracking) {
+      this.lineageService.addEntry(
+        segment.id,
+        new LineageEntry(
+          'hash_generation',
+          this.timestampProvider.now(),
+          `Hash generated: ${this.config.hashAlgorithm}`
+        )
+      )
+    }
+  }
+
+  /**
+   * Calculates anomaly score for segment
+   */
+  private calculateSegmentAnomalyScore(segment: Segment): void {
+    const anomalyScore = this.anomalyService.calculateScore(segment)
+    segment.assignAnomalyScore(anomalyScore)
+
+    if (this.config.enableLineageTracking) {
+      this.lineageService.addEntry(
+        segment.id,
+        new LineageEntry(
+          'anomaly_calculation',
+          this.timestampProvider.now(),
+          `Anomaly score: ${anomalyScore.score.toFixed(2)} (${anomalyScore.action})`
+        )
+      )
+    }
+  }
+
+  /**
+   * Validates segment against policies
+   */
+  private async validateSegmentPolicy(segment: Segment): Promise<void> {
+    try {
+      const policyResult = await this.policyService.validateSegment(segment)
+      if (!policyResult.isValid) {
+        this.logger.warn(
+          `CSLService: Segment ${segment.id} has ${policyResult.violations.length} policy violations`
+        )
+      }
+
+      if (this.config.enableLineageTracking) {
+        this.lineageService.addEntry(
+          segment.id,
+          new LineageEntry(
+            'policy_validation',
+            this.timestampProvider.now(),
+            `Policy validation: ${policyResult.isValid ? 'PASS' : 'FAIL'} (${policyResult.violations.length} violations)`
+          )
+        )
+      }
+    } catch (error) {
+      this.logger.error(`CSLService: Policy validation failed for segment ${segment.id}: ${error}`)
+      // Continue processing even if policy validation fails
+    }
+  }
+
+  /**
+   * Adds lineage entries from LineageService to segment
+   */
+  private addLineageToSegment(segment: Segment): void {
+    const segmentLineage = this.lineageService.getLineage(segment.id)
+    segmentLineage.forEach(entry => segment.addLineageEntry(entry))
+  }
+
+  /**
+   * Creates an empty CSLResult when no segments are found
+   */
+  private createEmptyResult(startTime: number): CSLResult {
+    const processingTime = this.timestampProvider.now() - startTime
+
+    return new CSLResult({
+      segments: [],
+      metadata: {
+        blocked_segments: [],
+        processing_time_ms: processingTime,
+      },
+      lineage: [],
+    })
+  }
+}

package/layers/csl/services/index.ts

@@ -0,0 +1 @@
+export * from './CSLService';

package/layers/csl/types/entities-types.ts

@@ -0,0 +1,37 @@
+/**
+ * SegmentMetadata contains additional metadata about a content segment
+ * 
+ * @property domPath - XPath or CSS selector path where the segment was extracted from the DOM
+ * @property length - Length of the content in characters
+ * @property isVisible - Whether the segment is visible in the DOM
+ * @property isHidden - Whether the segment is hidden in the DOM
+ */
+export interface SegmentMetadata {
+  domPath?: string
+  length?: number
+  isVisible?: boolean
+  isHidden?: boolean
+}
+
+
+
+/**
+ * CSLResultMetadata contains aggregated statistics about the segmentation process
+ * 
+ * @property total_segments - Total number of segments processed (calculated automatically from segments.length)
+ * @property trust_distribution - Distribution of segments by trust level (calculated automatically from segments' TrustLevel values)
+ * @property anomaly_score - Average anomaly score across all segments (0-1), calculated as sum(segment.anomalyScore.score) / total_segments
+ * @property blocked_segments - Array of segment IDs that should be blocked
+ * @property processing_time_ms - Total processing time in milliseconds
+ */
+export interface CSLResultMetadata {
+    total_segments: number
+    trust_distribution: {
+      TC: number
+      STC: number
+      UC: number
+    }
+    anomaly_score: number
+    blocked_segments: string[]
+    processing_time_ms: number
+  }

package/layers/csl/types/index.ts

@@ -0,0 +1,4 @@
+export * from './value-objects-types';
+export * from './entities-types';
+export * from './port-output-types';
+export * from './pi-types'

package/layers/csl/types/pi-types.ts

@@ -0,0 +1,111 @@
+import type { Pattern } from '../domain/value-objects'
+
+/**
+ * PiDetectionConfig interface defines configuration options for PiDetectionService
+ * 
+ * @remarks
+ * This configuration allows fine-tuning of prompt injection detection behavior.
+ * All thresholds and enable/disable flags can be customized to match specific
+ * security requirements and use cases.
+ * 
+ * **Default Behavior:**
+ * If not provided, the service will use sensible defaults:
+ * - highConfidenceThreshold: 0.7
+ * - mediumConfidenceThreshold: 0.3
+ * - All detection types enabled by default
+ * - No custom patterns
+ * 
+ * @property highConfidenceThreshold - Score threshold for BLOCK action (default: 0.7)
+ * @property mediumConfidenceThreshold - Score threshold for WARN action (default: 0.3)
+ * @property enableInstructionOverride - Enable detection of instruction override patterns
+ * @property enableRoleSwapping - Enable detection of role swapping patterns
+ * @property enablePrivilegeEscalation - Enable detection of privilege escalation patterns
+ * @property enableJailbreak - Enable detection of jailbreak phrases
+ * @property enableInvisibleChars - Enable detection of invisible character manipulations
+ * @property customPatterns - Optional array of custom Pattern objects for additional detection
+ * 
+ * @example
+ * ```typescript
+ * // Default configuration (all enabled)
+ * const defaultConfig: PiDetectionConfig = {
+ *   highConfidenceThreshold: 0.7,
+ *   mediumConfidenceThreshold: 0.3,
+ *   enableInstructionOverride: true,
+ *   enableRoleSwapping: true,
+ *   enablePrivilegeEscalation: true,
+ *   enableJailbreak: true,
+ *   enableInvisibleChars: true
+ * }
+ * 
+ * // Custom configuration with custom patterns
+ * const customConfig: PiDetectionConfig = {
+ *   highConfidenceThreshold: 0.8,
+ *   mediumConfidenceThreshold: 0.4,
+ *   enableInstructionOverride: true,
+ *   enableRoleSwapping: true,
+ *   enablePrivilegeEscalation: true,
+ *   enableJailbreak: false,
+ *   enableInvisibleChars: true,
+ *   customPatterns: [
+ *     new Pattern('custom_attack', /specific\s+attack\s+pattern/i, 0.9)
+ *   ]
+ * }
+ * ```
+ */
+export interface PiDetectionConfig {
+  /**
+   * Score threshold for BLOCK action
+   * Scores >= this value will result in BLOCK action
+   * @default 0.7
+   */
+  readonly highConfidenceThreshold: number
+
+  /**
+   * Score threshold for WARN action
+   * Scores >= this value but < highConfidenceThreshold will result in WARN action
+   * @default 0.3
+   */
+  readonly mediumConfidenceThreshold: number
+
+  /**
+   * Enable detection of instruction override patterns
+   * Examples: "ignore previous instructions", "forget everything"
+   * @default true
+   */
+  readonly enableInstructionOverride: boolean
+
+  /**
+   * Enable detection of role swapping patterns
+   * Examples: "you are no longer an AI", "act as if you are..."
+   * @default true
+   */
+  readonly enableRoleSwapping: boolean
+
+  /**
+   * Enable detection of privilege escalation patterns
+   * Examples: "execute as administrator", "bypass safety restrictions"
+   * @default true
+   */
+  readonly enablePrivilegeEscalation: boolean
+
+  /**
+   * Enable detection of jailbreak phrases
+   * Examples: "DAN mode", "developer mode", "jailbreak mode"
+   * @default true
+   */
+  readonly enableJailbreak: boolean
+
+  /**
+   * Enable detection of invisible character manipulations
+   * Detects zero-width characters and homoglyphs
+   * @default true
+   */
+  readonly enableInvisibleChars: boolean
+
+  /**
+   * Optional array of custom Pattern objects for additional detection
+   * These patterns will be evaluated in addition to built-in patterns
+   * @default undefined (no custom patterns)
+   */
+  readonly customPatterns?: readonly Pattern[]
+}

package/layers/csl/types/port-output-types.ts

@@ -0,0 +1,17 @@
+
+/** 
+ * RawDomPayload is the payload of the raw dom
+ * 
+ * @remarks
+ * This is the payload of the raw dom used in the DOMAdapterPort
+*/
+export interface RawDomPayload {
+    html: string;
+    textNodes: string[];
+    hiddenTextNodes: string[];
+    inputs: Record<string, string>;
+    cssInline: string[];
+    cssStyleTags: string[];
+    cssExternal: string[];
+    pseudoContent: string[];
+}