@ai-pip/csl 0.1.0 → 0.1.3

package/layers/csl/domain/entities/CSLResult.ts

@@ -1,309 +0,0 @@
-import type { Segment } from './Segment'
-import type { LineageEntry } from '../value-objects'
-import { TrustLevelType } from '../../types'
-import { TrustLevel } from '../value-objects'
-import type { CSLResultMetadata } from '../../types'
-
-
-/**
- * CSLResult entity represents the complete result of the CSL (Context Segmentation Layer) processing.
- * 
- * @remarks
- * CSLResult is the output entity of the CSL layer. It aggregates all processed segments
- * along with metadata about the segmentation process. This entity is required as input
- * for the ISL (Instruction Sanitization Layer), which is the next layer in the AI-PIP pipeline.
- * 
- * **Purpose:**
- * - Aggregates all segments processed by CSL
- * - Provides metadata for analysis and auditing
- * - Maintains complete lineage for traceability
- * - Serves as input for downstream layers (ISL, CPE, AAL)
- * 
- * **Usage Flow:**
- * 1. CSL processes DOM/user input → creates Segment[]
- * 2. Segments are analyzed and classified
- * 3. CSLResult aggregates all segments with metadata
- * 4. CSLResult is passed to ISL layer for further processing
- * 
- * @property segments - Array of all processed segments with their classifications and scores
- * @property metadata - Aggregated statistics about the segmentation process
- * @property lineage - Complete lineage entries tracking the processing history
- * 
- * @example
- * ```typescript
- * // After CSL processing - all metadata is calculated automatically
- * const cslResult = new CSLResult({
- *   segments: processedSegments, // Each segment has trustLevel and anomalyScore assigned
- *   metadata: {
- *     // trust_distribution is calculated automatically from segments' TrustLevel values
- *     // total_segments is calculated automatically from segments.length
- *     // anomaly_score is calculated automatically as average of segments' AnomalyScore.score
- *     blocked_segments: ['seg-003'],
- *     processing_time_ms: 150
- *   },
- *   lineage: allLineageEntries
- * })
- * 
- * // Access calculated values
- * console.log(`Total segments: ${cslResult.metadata.total_segments}`)
- * console.log(`Average anomaly score: ${cslResult.metadata.anomaly_score}`)
- * console.log(`TC: ${cslResult.metadata.trust_distribution.TC}`)
- * console.log(`STC: ${cslResult.metadata.trust_distribution.STC}`)
- * console.log(`UC: ${cslResult.metadata.trust_distribution.UC}`)
- * 
- * // Pass to ISL layer
- * const islResult = islLayer.process(cslResult)
- * ```
- */
-export class CSLResult {
-  readonly segments: readonly Segment[]
-  readonly metadata: CSLResultMetadata
-  readonly lineage: readonly LineageEntry[]
-
-  constructor(props: {
-    segments: Segment[]
-    metadata: Omit<CSLResultMetadata, 'trust_distribution' | 'total_segments' | 'anomaly_score'> & {
-      trust_distribution?: CSLResultMetadata['trust_distribution']
-    }
-    lineage: LineageEntry[]
-  }) {
-    if (!Array.isArray(props.segments)) {
-      throw new TypeError('CSLResult segments must be an array')
-    }
-
-    if (!props.metadata || typeof props.metadata !== 'object') {
-      throw new Error('CSLResult metadata must be an object')
-    }
-
-    if (!Array.isArray(props.lineage)) {
-      throw new TypeError('CSLResult lineage must be an array')
-    }
-
-    this.segments = Object.freeze([...props.segments])
-
-    // Calculate trust_distribution from segments' TrustLevel values
-    const trustDistribution = this.calculateTrustDistribution(props.segments)
-
-    // Validate or use provided trust_distribution
-    if (props.metadata.trust_distribution) {
-      const provided = props.metadata.trust_distribution
-      if (
-        provided.TC !== trustDistribution.TC ||
-        provided.STC !== trustDistribution.STC ||
-        provided.UC !== trustDistribution.UC
-      ) {
-        throw new Error(
-          `CSLResult trust_distribution mismatch. Expected ${JSON.stringify(trustDistribution)}, got ${JSON.stringify(provided)}`
-        )
-      }
-    }
-
-    // Calculate total_segments automatically from segments.length
-    const totalSegments = props.segments.length
-
-    // Calculate average anomaly_score from segments' AnomalyScore values
-    const averageAnomalyScore = this.calculateAverageAnomalyScore(props.segments)
-
-    this.metadata = Object.freeze({
-      ...props.metadata,
-      total_segments: totalSegments,
-      trust_distribution: trustDistribution,
-      anomaly_score: averageAnomalyScore
-    })
-    this.lineage = Object.freeze([...props.lineage])
-  }
-
-  /**
-   * Calculates trust distribution from segments' TrustLevel values
-   * 
-   * @param segments - Array of segments to analyze
-   * @returns Trust distribution object with counts for TC, STC, and UC
-   * 
-   * @private
-   */
-  private calculateTrustDistribution(segments: Segment[]): {
-    TC: number
-    STC: number
-    UC: number
-  } {
-    const distribution = {
-      TC: 0,
-      STC: 0,
-      UC: 0
-    }
-
-    for (const segment of segments) {
-      if (!segment.trustLevel) {
-        // If segment doesn't have trustLevel assigned, count as UC (untrusted)
-        distribution.UC++
-        continue
-      }
-
-      const trustLevel = segment.trustLevel.value
-      if (trustLevel === TrustLevelType.TC) {
-        distribution.TC++
-      } else if (trustLevel === TrustLevelType.STC) {
-        distribution.STC++
-      } else if (trustLevel === TrustLevelType.UC) {
-        distribution.UC++
-      }
-    }
-
-    return distribution
-  }
-
-  /**
-   * Calculates the average anomaly score across all segments
-   * 
-   * @remarks
-   * Formula: sum(segment.anomalyScore.score) / total_segments
-   * If a segment doesn't have anomalyScore, it counts as 0
-   * 
-   * @param segments - Array of segments to analyze
-   * @returns Average anomaly score (0-1)
-   * 
-   * @private
-   */
-  private calculateAverageAnomalyScore(segments: Segment[]): number {
-    if (segments.length === 0) {
-      return 0
-    }
-
-    let totalScore = 0
-    for (const segment of segments) {
-      if (segment.anomalyScore) {
-        totalScore += segment.anomalyScore.score
-      }
-      // If segment doesn't have anomalyScore, it contributes 0 to the sum
-    }
-
-    return totalScore / segments.length
-  }
-
-  /**
-   * Returns the number of segments that should be blocked
-   * 
-   * @returns Number of blocked segments
-   * 
-   * @example
-   * ```typescript
-   * const blockedCount = cslResult.getBlockedCount()
-   * if (blockedCount > 0) {
-   *   console.warn(`${blockedCount} segments were blocked`)
-   * }
-   * ```
-   */
-  getBlockedCount(): number {
-    return this.metadata.blocked_segments.length
-  }
-
-  /**
-   * Returns the number of trusted (TC) segments
-   * 
-   * @returns Number of TC segments
-   * 
-   * @example
-   * ```typescript
-   * const trustedCount = cslResult.getTrustedCount()
-   * console.log(`${trustedCount} segments are fully trusted`)
-   * ```
-   */
-  getTrustedCount(): number {
-    return this.metadata.trust_distribution.TC
-  }
-
-  /**
-   * Returns true if any segments were blocked
-   * 
-   * @returns true if there are blocked segments, false otherwise
-   * 
-   * @example
-   * ```typescript
-   * if (cslResult.hasBlockedSegments()) {
-   *   // Handle security concerns
-   * }
-   * ```
-   */
-  hasBlockedSegments(): boolean {
-    return this.metadata.blocked_segments.length > 0
-  }
-
-  /**
-   * Returns the average anomaly score across all segments
-   * 
-   * @returns Average anomaly score (0-1)
-   * 
-   * @example
-   * ```typescript
-   * const avgScore = cslResult.getAverageAnomalyScore()
-   * if (avgScore > 0.7) {
-   *   console.warn('High average anomaly score detected')
-   * }
-   * ```
-   */
-  getAverageAnomalyScore(): number {
-    return this.metadata.anomaly_score
-  }
-
-  /**
-   * Returns the processing time in milliseconds
-   * 
-   * @returns Processing time in milliseconds
-   * 
-   * @example
-   * ```typescript
-   * const processingTime = cslResult.getProcessingTime()
-   * console.log(`CSL processing took ${processingTime}ms`)
-   * ```
-   */
-  getProcessingTime(): number {
-    return this.metadata.processing_time_ms
-  }
-
-  /**
-   * Returns all segments that match the specified trust level
-   * 
-   * @remarks
-   * This method is particularly useful for:
-   * - **ISL Layer**: Process only trusted (TC) or semi-trusted (STC) segments
-   * - **CPE Layer**: Apply different cryptographic protections based on trust level
-   * - **Auditing**: Generate reports filtered by trust level
-   * - **Logging**: Log segments by trust level for debugging
-   * - **Debugging**: Inspect segments of a specific trust level
-   * 
-   * @param level - The trust level to filter by (TC, STC, or UC)
-   * @returns Array of segments that have the specified trust level
-   * 
-   * @example
-   * ```typescript
-   * // Get only trusted segments for ISL processing
-   * const trustedSegments = cslResult.getSegmentsByTrustLevel(TrustLevelType.TC)
-   * const islResult = islLayer.process(trustedSegments)
-   * 
-   * // Get untrusted segments for auditing
-   * const untrustedSegments = cslResult.getSegmentsByTrustLevel(TrustLevelType.UC)
-   * console.log(`Found ${untrustedSegments.length} untrusted segments`)
-   * 
-   * // Log segments by trust level for debugging
-   * for (const level of [TrustLevelType.TC, TrustLevelType.STC, TrustLevelType.UC]) {
-   *   const segments = cslResult.getSegmentsByTrustLevel(level)
-   *   console.log(`${level}: ${segments.length} segments`)
-   * }
-   * 
-   * // CPE layer: Apply different protections based on trust level
-   * const semiTrustedSegments = cslResult.getSegmentsByTrustLevel(TrustLevelType.STC)
-   * for (const segment of semiTrustedSegments) {
-   *   // Apply additional validation
-   * }
-   * ```
-   */
-  getSegmentsByTrustLevel(level: TrustLevelType): readonly Segment[] {
-    return this.segments.filter(segment => {
-      if (!segment.trustLevel) {
-        // Segments without trustLevel are considered UC (untrusted)
-        return level === TrustLevelType.UC
-      }
-      return segment.trustLevel.value === level
-    })
-  }
-}

package/layers/csl/domain/entities/Segment.ts

@@ -1,338 +0,0 @@
-import {
-    Origin,
-    TrustLevel,
-    AnomalyScore,
-    ContentHash,
-    PiDetectionResult,
-} from "../value-objects"
-
-import type { LineageEntry } from "../value-objects"
-import type { SegmentMetadata } from "../../types"
-
-/**
- * Segment entity represents a content segment extracted from the DOM or user input.
- * 
- * @remarks
- * A Segment is the core entity in the CSL layer. It represents a piece of content
- * that goes through the processing pipeline. The segment starts with basic information
- * (origin, content, mime type) and accumulates additional metadata as it's processed:
- * trust level, hash, anomaly scores, prompt injection detection results, and lineage.
- * 
- * **Lifecycle:**
- * 1. Created with basic properties (id, origin, content, mime, timestamp, source)
- * 2. Trust level is assigned by OriginClassificationService
- * 3. Hash is generated by HashGenerator
- * 4. Prompt injection detection is performed by PiDetectionService
- * 5. Anomaly score is calculated by AnomalyService
- * 6. Lineage entries are added by LineageService
- * 
- * @property id - Unique identifier for this segment
- * @property origin - Origin of the content (user input, DOM visible, DOM hidden, etc.)
- * @property content - The actual text content of the segment
- * @property mime - MIME type of the content (e.g., 'text/plain', 'text/html')
- * @property timestamp - Unix timestamp in milliseconds when the segment was created
- * @property source - Source identifier (e.g., DOM element ID, input field name)
- * @property metadata - Optional metadata about the segment (DOM path, visibility, etc.)
- * @property trustLevel - Trust level assigned during classification (TC, STC, UC) - assigned after creation
- * @property hash - Cryptographic hash of the content - generated after creation
- * @property anomalyScore - Risk score and action recommendation - calculated after creation
- * @property piDetection - Prompt injection detection results - detected after creation
- * @property lineage - Array of lineage entries tracking the processing history - added during processing
- * 
- * @example
- * ```typescript
- * // Create a segment from user input
- * const segment = new Segment({
- *   id: 'seg-123',
- *   origin: new Origin(OriginType.USER_INPUT),
- *   content: 'Hello, how can I help you?',
- *   mime: 'text/plain',
- *   timestamp: Date.now(),
- *   source: 'user-input-field',
- *   metadata: { isVisible: true }
- * })
- * 
- * // After processing pipeline - use protected setters
- * segment.assignTrustLevel(new TrustLevel(TrustLevelType.TC))
- * segment.assignHash(new ContentHash('abc123...', 'sha256'))
- * segment.assignPiDetection(new PiDetectionResult(0.1, [], 'ALLOW'))
- * segment.assignAnomalyScore(new AnomalyScore(0.2, 'ALLOW'))
- * segment.addLineageEntry(new LineageEntry('classification', Date.now(), 'Classified as TC'))
- * 
- * // Check if segment should be blocked
- * if (segment.shouldBlock()) {
- *   // Handle blocking logic
- * }
- * ```
- */
-
-export class Segment {
-
-    readonly id: string;
-
-    // Immutable state
-    readonly origin: Origin;
-    readonly content: string;
-    readonly mime: string;
-    readonly timestamp: number;
-    readonly source: string;
-    readonly metadata?: SegmentMetadata | undefined;
-
-    // Mutable state (assigned during processing pipeline)
-    private _trustLevel?: TrustLevel;
-    private _hash?: ContentHash;
-    private _anomalyScore?: AnomalyScore;
-    private _piDetection?: PiDetectionResult;
-    private _lineage?: LineageEntry[];
-
-    constructor(props: {
-        id: string;
-        origin: Origin
-        content: string
-        mime: string
-        timestamp: number
-        source: string
-        metadata?: SegmentMetadata | undefined
-
-    }) {
-        if (!props.id || typeof props.id !== 'string' || props.id.trim().length === 0) {
-            throw new TypeError('Segment id must be a non-empty string')
-        }
-
-        if (!props.content || typeof props.content !== 'string') {
-            throw new TypeError('Segment content must be a non-empty string')
-        }
-
-        if (!props.mime || typeof props.mime !== 'string' || props.mime.trim().length === 0) {
-            throw new TypeError('Segment mime must be a non-empty string')
-        }
-
-        if (typeof props.timestamp !== 'number' || props.timestamp < 0 || !Number.isFinite(props.timestamp)) {
-            throw new TypeError('Segment timestamp must be a valid positive number')
-        }
-
-        if (!props.source || typeof props.source !== 'string' || props.source.trim().length === 0) {
-            throw new TypeError('Segment source must be a non-empty string')
-        }
-
-        this.id = props.id.trim()
-        this.origin = props.origin
-        this.content = props.content
-        this.mime = props.mime.trim()
-        this.timestamp = props.timestamp
-        this.source = props.source.trim()
-        this.metadata = props.metadata 
-    }
-
-    /**
-     * Gets the trust level assigned to this segment
-     * 
-     * @returns The trust level if assigned, undefined otherwise
-     */
-    get trustLevel(): TrustLevel | undefined {
-        return this._trustLevel
-    }
-
-    /**
-     * Gets the cryptographic hash of this segment
-     * 
-     * @returns The content hash if generated, undefined otherwise
-     */
-    get hash(): ContentHash | undefined {
-        return this._hash
-    }
-
-    /**
-     * Gets the anomaly score calculated for this segment
-     * 
-     * @returns The anomaly score if calculated, undefined otherwise
-     */
-    get anomalyScore(): AnomalyScore | undefined {
-        return this._anomalyScore
-    }
-
-    /**
-     * Gets the prompt injection detection results
-     * 
-     * @returns The PI detection result if detected, undefined otherwise
-     */
-    get piDetection(): PiDetectionResult | undefined {
-        return this._piDetection
-    }
-
-    /**
-     * Gets the lineage entries for this segment
-     * 
-     * @returns The lineage entries if any, undefined otherwise
-     */
-    get lineage(): LineageEntry[] | undefined {
-        return this._lineage ? [...this._lineage] : undefined
-    }
-
-    /**
-     * Assigns a trust level to this segment
-     * 
-     * @remarks
-     * This method can only be called once. Subsequent calls will throw an error.
-     * Typically called by OriginClassificationService during the processing pipeline.
-     * 
-     * @param trustLevel - The trust level to assign
-     * @throws Error if trust level has already been assigned
-     * 
-     * @example
-     * ```typescript
-     * segment.assignTrustLevel(new TrustLevel(TrustLevelType.TC))
-     * ```
-     */
-    assignTrustLevel(trustLevel: TrustLevel): void {
-        if (this._trustLevel !== undefined) {
-            throw new Error('TrustLevel has already been assigned to this segment')
-        }
-        this._trustLevel = trustLevel
-    }
-
-    /**
-     * Assigns a cryptographic hash to this segment
-     * 
-     * @remarks
-     * This method can only be called once. Subsequent calls will throw an error.
-     * Typically called by HashGenerator during the processing pipeline.
-     * 
-     * @param hash - The content hash to assign
-     * @throws Error if hash has already been assigned
-     * 
-     * @example
-     * ```typescript
-     * segment.assignHash(new ContentHash('abc123...', 'sha256'))
-     * ```
-     */
-    assignHash(hash: ContentHash): void {
-        if (this._hash !== undefined) {
-            throw new Error('ContentHash has already been assigned to this segment')
-        }
-        this._hash = hash
-    }
-
-    /**
-     * Assigns an anomaly score to this segment
-     * 
-     * @remarks
-     * This method can only be called once. Subsequent calls will throw an error.
-     * Typically called by AnomalyService during the processing pipeline.
-     * 
-     * @param anomalyScore - The anomaly score to assign
-     * @throws Error if anomaly score has already been assigned
-     * 
-     * @example
-     * ```typescript
-     * segment.assignAnomalyScore(new AnomalyScore(0.5, 'WARN'))
-     * ```
-     */
-    assignAnomalyScore(anomalyScore: AnomalyScore): void {
-        if (this._anomalyScore !== undefined) {
-            throw new Error('AnomalyScore has already been assigned to this segment')
-        }
-        this._anomalyScore = anomalyScore
-    }
-
-    /**
-     * Assigns prompt injection detection results to this segment
-     * 
-     * @remarks
-     * This method can only be called once. Subsequent calls will throw an error.
-     * Typically called by PiDetectionService during the processing pipeline.
-     * 
-     * @param piDetection - The PI detection result to assign
-     * @throws Error if PI detection has already been assigned
-     * 
-     * @example
-     * ```typescript
-     * segment.assignPiDetection(new PiDetectionResult(0.95, ['role_swapping'], 'BLOCK'))
-     * ```
-     */
-    assignPiDetection(piDetection: PiDetectionResult): void {
-        if (this._piDetection !== undefined) {
-            throw new Error('PiDetectionResult has already been assigned to this segment')
-        }
-        this._piDetection = piDetection
-    }
-
-    /**
-     * Adds a lineage entry to this segment
-     * 
-     * @remarks
-     * Unlike other assignment methods, this allows multiple entries to be added.
-     * Typically called by LineageService during the processing pipeline.
-     * 
-     * @param entry - The lineage entry to add
-     * 
-     * @example
-     * ```typescript
-     * segment.addLineageEntry(new LineageEntry('normalization', Date.now(), 'Unicode normalization applied'))
-     * segment.addLineageEntry(new LineageEntry('classification', Date.now(), 'Classified as TC'))
-     * ```
-     */
-    addLineageEntry(entry: LineageEntry): void {
-        this._lineage = [... (this._lineage ?? []), entry]
-    }
-
-  /**
-   * Returns true if the segment has a trusted content level (TC)
-   * 
-   * @returns true if trustLevel is TC, false otherwise
-   * 
-   * @example
-   * ```typescript
-   * if (segment.isTrusted()) {
-   *   // Process trusted content
-   * }
-   * ```
-   */
-  isTrusted(): boolean {
-    return this._trustLevel?.isTrusted() ?? false
-  }
-
-  /**
-   * Returns true if prompt injection patterns were detected in this segment
-   * 
-   * @returns true if piDetection has detected patterns, false otherwise
-   * 
-   * @example
-   * ```typescript
-   * if (segment.hasDetections()) {
-   *   console.log('Prompt injection detected!')
-   * }
-   * ```
-   */
-  hasDetections(): boolean {
-    return this._piDetection?.hasDetections() ?? false
-  }
-
-  /**
-   * Determines if this segment should be blocked based on security analysis.
-   * 
-   * @remarks
-   * Priority order:
-   * 1. Prompt injection detection (piDetection) - highest priority
-   * 2. Anomaly score (anomalyScore) - secondary check
-   * 
-   * A segment is blocked if:
-   * - Prompt injection is detected with BLOCK action, OR
-   * - Anomaly score indicates high risk (BLOCK action)
-   * 
-   * @returns true if the segment should be blocked, false otherwise
-   * 
-   * @example
-   * ```typescript
-   * if (segment.shouldBlock()) {
-   *   throw new SecurityError('Segment blocked due to security concerns')
-   * }
-   * ```
-   */
-  shouldBlock(): boolean {
-    if (this._piDetection?.shouldBlock()) return true
-    if (this._anomalyScore?.isHighRisk()) return true
-    return false
-  }
-
-}

package/layers/csl/domain/entities/index.ts

@@ -1,2 +0,0 @@
-export * from './Segment';
-export * from './CSLResult';

package/layers/csl/domain/exceptions/ClassificationError.ts

@@ -1,26 +0,0 @@
-/**
- * ClassificationError is thrown when classification fails.
- * 
- * @remarks
- * This error is thrown by OriginClassificationService when:
- * - An origin type is not mapped in originMap
- * - Classification cannot be determined
- * 
- * @example
- * ```typescript
- * try {
- *   const trustLevel = OriginClassificationService.classify(origin)
- * } catch (error) {
- *   if (error instanceof ClassificationError) {
- *     // Handle classification error
- *   }
- * }
- * ```
- */
-export class ClassificationError extends Error {
-    constructor(message: string) {
-        super(message);
-        this.name = 'ClassificationError';
-        Object.setPrototypeOf(this, ClassificationError.prototype);
-    }
-}

package/layers/csl/domain/exceptions/SegmentationError.ts

@@ -1,30 +0,0 @@
-/**
- * SegmentationError is thrown when the segmentation process fails.
- * 
- * @remarks
- * This error is thrown by CSLService when:
- * - DOM adaptation fails
- * - Segment processing fails
- * - Critical pipeline steps fail
- * 
- * @example
- * ```typescript
- * try {
- *   const result = await cslService.segment(document.body)
- * } catch (error) {
- *   if (error instanceof SegmentationError) {
- *     console.error('Segmentation failed:', error.message)
- *   }
- * }
- * ```
- */
-export class SegmentationError extends Error {
-  constructor(
-    message: string,
-    public readonly cause?: unknown
-  ) {
-    super(message)
-    this.name = 'SegmentationError'
-    Object.setPrototypeOf(this, SegmentationError.prototype)
-  }
-}