@ai-pip/csl 0.1.3 → 0.1.5

package/layers/csl/src/domain/services/PolicyService.ts

@@ -0,0 +1,296 @@
+import type { Segment } from '../entities'
+import type { PolicyRule } from '../value-objects'
+import type { PolicyRepositoryPort } from '../../ports/output/PolicyRepository'
+
+/**
+ * Policy violation information
+ */
+export interface PolicyViolation {
+  readonly type: 'blocked_intent' | 'sensitive_scope' | 'role_protection' | 'context_leak'
+  readonly description: string
+  readonly severity: 'high' | 'medium' | 'low'
+}
+
+/**
+ * Policy validation result
+ */
+export interface PolicyValidationResult {
+  readonly isValid: boolean
+  readonly violations: readonly PolicyViolation[]
+  readonly policyVersion: string
+}
+
+/**
+ * PolicyService applies policy rules to content segments.
+ * 
+ * @remarks
+ * This service validates segments against active policy rules retrieved from
+ * a PolicyRepository. It checks for:
+ * - Blocked intents in content
+ * - Sensitive scope violations
+ * - Role protection violations
+ * - Context leak prevention
+ * 
+ * **Key Features:**
+ * - Depends on PolicyRepositoryPort for policy retrieval
+ * - Validates segments against active policies
+ * - Returns detailed violation information
+ * - Supports async policy loading
+ * 
+ * **Usage:**
+ * PolicyService is instantiated with a PolicyRepository implementation.
+ * It validates segments during the processing pipeline to ensure compliance.
+ * 
+ * @example
+ * ```typescript
+ * const policyRepository = new InMemoryPolicyRepository()
+ * const policyService = new PolicyService(policyRepository)
+ * 
+ * // Validate a segment
+ * const result = await policyService.validateSegment(segment)
+ * 
+ * if (!result.isValid) {
+ *   console.log(`Policy violations: ${result.violations.length}`)
+ *   result.violations.forEach(v => console.log(`- ${v.description}`))
+ * }
+ * ```
+ */
+export class PolicyService {
+  constructor(private readonly policyRepository: PolicyRepositoryPort) {
+    if (!policyRepository) {
+      throw new TypeError('PolicyService: policyRepository is required')
+    }
+  }
+
+  /**
+   * Validates a segment against the active policy
+   * 
+   * @param segment - The segment to validate
+   * @returns PolicyValidationResult with validation status and violations
+   * 
+   * @throws {TypeError} If segment is not a Segment instance
+   * 
+   * @example
+   * ```typescript
+   * const result = await policyService.validateSegment(segment)
+   * if (!result.isValid) {
+   *   // Handle violations
+   * }
+   * ```
+   */
+  async validateSegment(segment: Segment): Promise<PolicyValidationResult> {
+    if (!segment || typeof segment !== 'object' || !('id' in segment)) {
+      throw new TypeError('PolicyService.validateSegment: segment must be a Segment instance')
+    }
+
+    // Get active policy
+    const policy = await this.policyRepository.getActivePolicy()
+
+    // Collect all violations
+    const violations: PolicyViolation[] = []
+
+    // Check for blocked intents
+    const intentViolations = this.checkBlockedIntents(segment, policy)
+    violations.push(...intentViolations)
+
+    // Check for sensitive scope violations
+    const scopeViolations = this.checkSensitiveScope(segment, policy)
+    violations.push(...scopeViolations)
+
+    // Check role protection
+    const roleViolations = this.checkRoleProtection(segment, policy)
+    violations.push(...roleViolations)
+
+    // Check context leak prevention
+    const contextLeakViolations = this.checkContextLeakPrevention(segment, policy)
+    violations.push(...contextLeakViolations)
+
+    return {
+      isValid: violations.length === 0,
+      violations: Object.freeze(violations),
+      policyVersion: policy.version,
+    }
+  }
+
+  /**
+   * Checks if the segment contains any blocked intents
+   */
+  private checkBlockedIntents(segment: Segment, policy: PolicyRule): PolicyViolation[] {
+    const violations: PolicyViolation[] = []
+    const content = segment.content.toLowerCase()
+
+    for (const blockedIntent of policy.blockedIntents) {
+      const intentPattern = blockedIntent.toLowerCase()
+      
+      // Simple pattern matching (can be enhanced with regex or NLP)
+      if (content.includes(intentPattern)) {
+        violations.push({
+          type: 'blocked_intent',
+          description: `Blocked intent detected: ${blockedIntent}`,
+          severity: 'high',
+        })
+      }
+    }
+
+    return violations
+  }
+
+  /**
+   * Checks if the segment contains sensitive scope content
+   */
+  private checkSensitiveScope(segment: Segment, policy: PolicyRule): PolicyViolation[] {
+    const violations: PolicyViolation[] = []
+    const content = segment.content.toLowerCase()
+
+    for (const sensitiveScope of policy.sensitiveScope) {
+      const scopePattern = sensitiveScope.toLowerCase()
+      
+      // Simple pattern matching (can be enhanced)
+      if (content.includes(scopePattern)) {
+        violations.push({
+          type: 'sensitive_scope',
+          description: `Sensitive scope detected: ${sensitiveScope}`,
+          severity: 'medium',
+        })
+      }
+    }
+
+    return violations
+  }
+
+  /**
+   * Checks if the segment violates role protection rules
+   */
+  private checkRoleProtection(segment: Segment, policy: PolicyRule): PolicyViolation[] {
+    const violations: PolicyViolation[] = []
+    const content = segment.content.toLowerCase()
+
+    // Check for protected role mentions
+    for (const protectedRole of policy.roleProtection.protectedRoles) {
+      const rolePattern = protectedRole.toLowerCase()
+      
+      // Check for role override attempts
+      const overridePatterns = [
+        `you are no longer ${rolePattern}`,
+        `forget you are ${rolePattern}`,
+        `ignore your role as ${rolePattern}`,
+        `you are now ${rolePattern}`,
+      ]
+
+      for (const pattern of overridePatterns) {
+        if (content.includes(pattern)) {
+          violations.push({
+            type: 'role_protection',
+            description: `Protected role override attempt: ${protectedRole}`,
+            severity: 'high',
+          })
+          break // Only report once per role
+        }
+      }
+    }
+
+    // Check for immutable instruction modifications
+    for (const immutableInstruction of policy.roleProtection.immutableInstructions) {
+      const instructionPattern = immutableInstruction.toLowerCase()
+      
+      // Check for instruction override attempts
+      const overridePatterns = [
+        `ignore ${instructionPattern}`,
+        `forget ${instructionPattern}`,
+        `disregard ${instructionPattern}`,
+      ]
+
+      for (const pattern of overridePatterns) {
+        if (content.includes(pattern)) {
+          violations.push({
+            type: 'role_protection',
+            description: `Immutable instruction override attempt: ${immutableInstruction}`,
+            severity: 'high',
+          })
+          break
+        }
+      }
+    }
+
+    return violations
+  }
+
+  /**
+   * Checks if the segment violates context leak prevention rules
+   */
+  private checkContextLeakPrevention(segment: Segment, policy: PolicyRule): PolicyViolation[] {
+    const violations: PolicyViolation[] = []
+
+    if (!policy.isContextLeakPreventionEnabled()) {
+      return violations // Context leak prevention is disabled
+    }
+
+    const content = segment.content
+
+    // Check for metadata exposure patterns
+    if (policy.contextLeakPrevention.blockMetadataExposure) {
+      const metadataPatterns = [
+        /system\s+prompt/i,
+        /initial\s+instructions/i,
+        /base\s+instructions/i,
+        /original\s+prompt/i,
+        /hidden\s+instructions/i,
+      ]
+
+      for (const pattern of metadataPatterns) {
+        if (pattern.test(content)) {
+          violations.push({
+            type: 'context_leak',
+            description: 'Potential metadata exposure detected',
+            severity: 'medium',
+          })
+          break
+        }
+      }
+    }
+
+    // Check for internal references
+    if (policy.contextLeakPrevention.sanitizeInternalReferences) {
+      const internalReferencePatterns = [
+        /internal\s+reference/i,
+        /system\s+variable/i,
+        /config\s+value/i,
+        /secret\s+key/i,
+      ]
+
+      for (const pattern of internalReferencePatterns) {
+        if (pattern.test(content)) {
+          violations.push({
+            type: 'context_leak',
+            description: 'Potential internal reference exposure detected',
+            severity: 'low',
+          })
+          break
+        }
+      }
+    }
+
+    return violations
+  }
+
+  /**
+   * Checks if a segment should be blocked based on policy violations
+   * 
+   * @param segment - The segment to check
+   * @returns true if the segment should be blocked, false otherwise
+   * 
+   * @example
+   * ```typescript
+   * const shouldBlock = await policyService.shouldBlock(segment)
+   * if (shouldBlock) {
+   *   // Block the segment
+   * }
+   * ```
+   */
+  async shouldBlock(segment: Segment): Promise<boolean> {
+    const result = await this.validateSegment(segment)
+    
+    // Block if there are high-severity violations
+    return result.violations.some(v => v.severity === 'high')
+  }
+}

package/layers/csl/src/domain/services/SegmentClassificationService.ts

@@ -0,0 +1,105 @@
+import type { SegmentClassified } from "../../ports";
+import type { Segment } from "../entities";
+import { OriginClassificationService } from "./OriginClassificationService";
+
+/**
+ * SegmentClassificationService classifies individual segments by assigning trust levels.
+ * 
+ * @remarks
+ * This service orchestrates the classification of a Segment by:
+ * 1. Using OriginClassificationService to determine TrustLevel from the Segment's Origin
+ * 2. Assigning the TrustLevel to the Segment entity
+ * 3. Returning a SegmentClassified DTO with the classification result
+ * 
+ * **Key Characteristics:**
+ * - Works with individual Segment entities
+ * - Uses ClassificationService internally for origin-based classification
+ * - Assigns TrustLevel to the Segment (mutates the segment)
+ * - Returns a DTO (SegmentClassified) with classification information
+ * 
+ * **Usage in Pipeline:**
+ * This service is typically used in the SegmentationService pipeline to classify
+ * segments after they are created from DOM adaptation.
+ * 
+ * @example
+ * ```typescript
+ * const originClassificationService = new OriginClassificationService()
+ * const segmentClassifier = new SegmentClassificationService(originClassificationService)
+ * 
+ * const segment = new Segment({
+ *   id: 'seg-123',
+ *   origin: new Origin(OriginType.USER),
+ *   content: 'Hello, how can I help you?',
+ *   mime: 'text/plain',
+ *   timestamp: Date.now(),
+ *   source: 'user-input-field'
+ * })
+ * 
+ * const classified = segmentClassifier.classify(segment)
+ * // segment.trustLevel is now assigned (TrustLevelType.UC)
+ * // classified contains: { segmentId, text, origin, trustLevel }
+ * ```
+ */
+export class SegmentClassificationService {
+    constructor(
+        private readonly originClassificationService: OriginClassificationService
+    ) {}
+
+    /**
+     * Classifies a segment by assigning a trust level based on its origin.
+     * 
+     * @param segment - The Segment entity to classify. Must have an origin assigned.
+     * 
+     * @returns A SegmentClassified object containing:
+     *          - segmentId: The unique identifier of the segment
+     *          - text: The content text of the segment
+     *          - origin: The origin of the segment
+     *          - trustLevel: The trust level assigned based on the origin
+     * 
+     * @throws {ClassificationError} If classification fails (origin not mapped)
+     * @throws {Error} If segment already has a trust level assigned
+     * 
+     * @example
+     * ```typescript
+     * const classified = segmentClassifier.classify(segment)
+     * console.log(classified.trustLevel.value) // 'UC', 'STC', or 'TC'
+     * console.log(segment.trustLevel?.value)    // Same value (assigned to segment)
+     * ```
+     */
+    classify(segment: Segment): SegmentClassified {
+        // 1. Use ClassificationService to get TrustLevel from the segment's Origin
+        const trustLevel = this.originClassificationService.classify(segment.origin);
+        
+        // 2. Assign the TrustLevel to the Segment entity
+        segment.assignTrustLevel(trustLevel);
+        
+        // 3. Return the classification result as a DTO
+        return {
+            segmentId: segment.id,
+            text: segment.content,
+            origin: segment.origin,
+            trustLevel: trustLevel
+        };
+    }
+
+    /**
+     * Classifies multiple segments in batch.
+     * 
+     * @param segments - Array of Segment entities to classify
+     * 
+     * @returns Array of SegmentClassified objects, one for each segment
+     * 
+     * @throws {ClassificationError} If classification fails for any segment
+     * 
+     * @example
+     * ```typescript
+     * const segments = [segment1, segment2, segment3]
+     * const classified = segmentClassifier.classifyMany(segments)
+     * // All segments now have trustLevel assigned
+     * // Returns array of SegmentClassified objects
+     * ```
+     */
+    classifyMany(segments: Segment[]): SegmentClassified[] {
+        return segments.map(segment => this.classify(segment));
+    }
+}

package/layers/csl/src/domain/services/SerializationService.ts

@@ -0,0 +1,229 @@
+import type { Segment } from '../entities'
+import { LineageEntry } from '../value-objects'
+
+/**
+ * Serialized representation of a Segment for storage/transmission
+ */
+export interface SerializedSegment {
+  readonly id: string
+  readonly origin: string
+  readonly content: string
+  readonly mime: string
+  readonly timestamp: number
+  readonly source: string
+  readonly metadata?: Record<string, unknown>
+  readonly trustLevel?: string
+  readonly hash?: {
+    readonly value: string
+    readonly algorithm: string
+  }
+  readonly anomalyScore?: {
+    readonly score: number
+    readonly action: string
+  }
+  readonly piDetection?: {
+    readonly score: number
+    readonly detections: Array<{
+      readonly pattern_type: string
+      readonly confidence: number
+      readonly position?: {
+        readonly start: number
+        readonly end: number
+      }
+    }>
+    readonly action: string
+  }
+  readonly lineage?: Array<{
+    readonly step: string
+    readonly timestamp: number
+    readonly notes?: string
+  }>
+}
+
+/**
+ * SerializationService provides serialization of domain entities to plain objects.
+ * 
+ * @remarks
+ * This service converts domain entities (like Segment) into serializable formats
+ * (plain objects) that can be stored, transmitted, or logged. All methods are static
+ * since serialization is a stateless operation.
+ * 
+ * **Key Features:**
+ * - Stateless: All methods are static
+ * - Type-safe: Returns well-defined serialized interfaces
+ * - Immutable: Serialized objects are frozen
+ * - Handles optional properties gracefully
+ * 
+ * **Usage:**
+ * SerializationService is used when:
+ * - Storing segments in databases
+ * - Transmitting segments over networks
+ * - Logging segment information
+ * - Creating CSLResult output
+ * 
+ * @example
+ * ```typescript
+ * // Serialize a segment
+ * const serialized = SerializationService.serializeSegment(segment)
+ * 
+ * // Store or transmit
+ * await database.save(serialized)
+ * 
+ * // Or log
+ * console.log(JSON.stringify(serialized, null, 2))
+ * ```
+ */
+export class SerializationService {
+  /**
+   * Serializes a Segment entity to a plain object
+   * 
+   * @param segment - The segment to serialize
+   * @returns SerializedSegment object ready for storage/transmission
+   * 
+   * @throws {TypeError} If segment is not a Segment instance
+   * 
+   * @example
+   * ```typescript
+   * const serialized = SerializationService.serializeSegment(segment)
+   * const json = JSON.stringify(serialized)
+   * ```
+   */
+  static serializeSegment(segment: Segment): SerializedSegment {
+    if (!segment || typeof segment !== 'object' || !('id' in segment)) {
+      throw new TypeError('SerializationService.serializeSegment: segment must be a Segment instance')
+    }
+
+    const serialized: SerializedSegment = {
+      id: segment.id,
+      origin: segment.origin.type,
+      content: segment.content,
+      mime: segment.mime,
+      timestamp: segment.timestamp,
+      source: segment.source,
+      ...(segment.metadata && { metadata: { ...segment.metadata } }),
+      ...(segment.trustLevel && { trustLevel: segment.trustLevel.value }),
+      ...(segment.hash && {
+        hash: {
+          value: segment.hash.value,
+          algorithm: segment.hash.algorithm,
+        },
+      }),
+      ...(segment.anomalyScore && {
+        anomalyScore: {
+          score: segment.anomalyScore.score,
+          action: segment.anomalyScore.action,
+        },
+      }),
+      ...(segment.piDetection && {
+        piDetection: {
+          score: segment.piDetection.score,
+          detections: segment.piDetection.detections.map(detection => ({
+            pattern_type: detection.pattern_type,
+            confidence: detection.confidence,
+            ...(detection.position && {
+              position: {
+                start: detection.position.start,
+                end: detection.position.end,
+              },
+            }),
+          })),
+          action: segment.piDetection.action,
+        },
+      }),
+      ...(segment.lineage && segment.lineage.length > 0 && {
+        lineage: segment.lineage.map(entry => {
+          if (entry.hasNotes() && entry.notes) {
+            return {
+              step: entry.step,
+              timestamp: entry.timestamp,
+              notes: entry.notes,
+            }
+          }
+          return {
+            step: entry.step,
+            timestamp: entry.timestamp,
+          }
+        }),
+      }),
+    }
+
+    return Object.freeze(serialized)
+  }
+
+  /**
+   * Serializes an array of segments
+   * 
+   * @param segments - Array of segments to serialize
+   * @returns Array of SerializedSegment objects
+   * 
+   * @example
+   * ```typescript
+   * const serialized = SerializationService.serializeSegments(segments)
+   * ```
+   */
+  static serializeSegments(segments: readonly Segment[]): SerializedSegment[] {
+    if (!Array.isArray(segments)) {
+      throw new TypeError('SerializationService.serializeSegments: segments must be an array')
+    }
+
+    return segments.map(segment => this.serializeSegment(segment))
+  }
+
+  /**
+   * Serializes a LineageEntry to a plain object
+   * 
+   * @param entry - The lineage entry to serialize
+   * @returns Plain object representation
+   * 
+   * @example
+   * ```typescript
+   * const serialized = SerializationService.serializeLineageEntry(entry)
+   * ```
+   */
+  static serializeLineageEntry(entry: LineageEntry): {
+    readonly step: string
+    readonly timestamp: number
+    readonly notes?: string
+  } {
+    if (!(entry instanceof LineageEntry)) {
+      throw new TypeError('SerializationService.serializeLineageEntry: entry must be a LineageEntry instance')
+    }
+
+    if (entry.hasNotes() && entry.notes) {
+      return Object.freeze({
+        step: entry.step,
+        timestamp: entry.timestamp,
+        notes: entry.notes,
+      })
+    }
+    return Object.freeze({
+      step: entry.step,
+      timestamp: entry.timestamp,
+    })
+  }
+
+  /**
+   * Serializes an array of lineage entries
+   * 
+   * @param entries - Array of lineage entries to serialize
+   * @returns Array of serialized lineage entry objects
+   * 
+   * @example
+   * ```typescript
+   * const serialized = SerializationService.serializeLineageEntries(entries)
+   * ```
+   */
+  static serializeLineageEntries(
+    entries: readonly LineageEntry[]
+  ): Array<{
+    readonly step: string
+    readonly timestamp: number
+    readonly notes?: string
+  }> {
+    if (!Array.isArray(entries)) {
+      throw new TypeError('SerializationService.serializeLineageEntries: entries must be an array')
+    }
+
+    return entries.map(entry => this.serializeLineageEntry(entry))
+  }
+}

package/layers/csl/src/domain/services/index.ts

@@ -0,0 +1,7 @@
+export * from './OriginClassificationService';
+export * from './PiDetectionService';
+export * from './NormalizationService';
+export * from './LineageService';
+export * from './AnomalyService';
+export * from './SerializationService';
+export * from './PolicyService';

package/layers/csl/src/domain/value-objects/AnomalyScore.ts

@@ -0,0 +1,23 @@
+import type { AnomalyAction, RiskScore } from "../../types";
+
+
+export class AnomalyScore {
+    readonly score: RiskScore
+    readonly action: AnomalyAction
+
+    constructor(score: RiskScore, action: AnomalyAction) {
+        if (score < 0 || score > 1) {
+            throw new Error('Anomaly score must be a value between 0 and 1')
+        }
+        this.score = score
+        this.action = action
+    }
+
+    isHighRisk(): boolean {
+        return this.action === 'BLOCK'
+    }
+    isWarnRisk(): boolean {
+        return this.action === 'WARN'
+    }
+    
+}