@ai-pip/csl 0.1.1 → 0.1.3

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

@@ -1,17 +0,0 @@
-
-
-/**
- * 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

@@ -1,29 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

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

package/layers/csl/services/CSLService.ts

@@ -1,393 +0,0 @@
-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

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

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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,4 +0,0 @@
-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

@@ -1,111 +0,0 @@
-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

@@ -1,17 +0,0 @@
-
-/** 
- * 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[];
-}