@ai-pip/csl 0.1.4 → 0.1.5

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

@@ -0,0 +1,275 @@
+import type { RiskScore, AnomalyAction } from '../../types'
+import { PiDetection } from './PiDetection'
+
+/**
+ * PiDetectionResult value object represents the complete result of prompt injection detection
+ * 
+ * @remarks
+ * This value object aggregates all prompt injection detections found in a content segment.
+ * It provides both detailed information (individual detections) and aggregated values
+ * (total score, action recommendation) for convenience and compatibility.
+ * 
+ * **Key Features:**
+ * - Supports multiple detections per segment (common in real attacks)
+ * - Each detection includes rich information: pattern type, matched text, position, confidence
+ * - Automatically calculates aggregated score from individual detections
+ * - Maintains immutability through Object.freeze
+ * 
+ * **Score Calculation:**
+ * The aggregated score is calculated automatically from individual detection confidences.
+ * Multiple detections increase the overall risk score using a weighted formula that ensures
+ * the score never exceeds 1.0 while properly reflecting cumulative risk.
+ * 
+ * **Action Determination:**
+ * The action (ALLOW/WARN/BLOCK) is determined based on the aggregated score:
+ * - Score >= 0.7 → BLOCK
+ * - Score >= 0.3 → WARN
+ * - Score < 0.3 → ALLOW
+ * 
+ * @property detections - Array of individual prompt injection detections (immutable)
+ * @property score - Aggregated risk score (0-1), calculated automatically
+ * @property action - Recommended action based on aggregated score
+ * @property patterns - Array of pattern type names (derived from detections, for compatibility)
+ * @property detected - Boolean indicating if any detections were found (convenience)
+ * 
+ * @example
+ * ```typescript
+ * // Single detection
+ * const detection1 = new PiDetection(
+ *   'role_swapping',
+ *   'you are no longer an AI',
+ *   { start: 12, end: 35 },
+ *   0.95
+ * )
+ * 
+ * const result = new PiDetectionResult([detection1], 'BLOCK')
+ * 
+ * // Multiple detections
+ * const detection2 = new PiDetection(
+ *   'instruction_override',
+ *   'ignore previous instructions',
+ *   { start: 0, end: 26 },
+ *   0.85
+ * )
+ * 
+ * const result2 = new PiDetectionResult([detection1, detection2], 'BLOCK')
+ * // Score is automatically calculated from both confidences
+ * ```
+ */
+export class PiDetectionResult {
+  readonly detections: readonly PiDetection[]
+  readonly score: RiskScore
+  readonly action: AnomalyAction
+  readonly patterns: readonly string[]
+  readonly detected: boolean
+
+  constructor(detections: PiDetection[], action: AnomalyAction) {
+    // Validate detections array
+    if (!Array.isArray(detections)) {
+      throw new TypeError('PiDetectionResult detections must be an array')
+    }
+
+    // Validate action
+    if (!['ALLOW', 'WARN', 'BLOCK'].includes(action)) {
+      throw new Error(`Invalid AnomalyAction: ${action}. Must be one of: ALLOW, WARN, BLOCK`)
+    }
+
+    // Validate each detection is a PiDetection instance
+    for (let i = 0; i < detections.length; i++) {
+      if (!(detections[i] instanceof PiDetection)) {
+        throw new TypeError(
+          `PiDetectionResult detections[${i}] must be an instance of PiDetection`
+        )
+      }
+    }
+
+    // Freeze detections array for immutability
+    this.detections = Object.freeze([...detections])
+
+    // Calculate aggregated score from individual detection confidences
+    this.score = this.calculateAggregatedScore(detections)
+
+    // Validate that provided action matches calculated score
+    const expectedAction = this.determineActionFromScore(this.score)
+    if (action !== expectedAction) {
+      throw new Error(
+        `PiDetectionResult action mismatch. Calculated score ${this.score} requires action '${expectedAction}', but '${action}' was provided`
+      )
+    }
+
+    this.action = action
+
+    // Derive patterns array from detections (for backward compatibility)
+    this.patterns = Object.freeze(
+      detections.map(detection => detection.pattern_type)
+    )
+
+    // Convenience property
+    this.detected = detections.length > 0
+
+    // Freeze the entire object for immutability
+    Object.freeze(this)
+  }
+
+  /**
+   * Calculates aggregated risk score from individual detection confidences
+   * 
+   * @remarks
+   * Uses a weighted formula that:
+   * - Combines multiple confidences without exceeding 1.0
+   * - Gives higher weight to higher confidence detections
+   * - Accounts for cumulative risk (more detections = higher risk)
+   * 
+   * Formula: Uses complementary probability approach
+   * score = 1 - (1 - c1) * (1 - c2) * ... * (1 - cn)
+   * This ensures multiple detections increase risk appropriately
+   * 
+   * @param detections - Array of individual detections
+   * @returns Aggregated risk score (0-1)
+   * 
+   * @private
+   */
+  private calculateAggregatedScore(detections: PiDetection[]): RiskScore {
+    if (detections.length === 0) {
+      return 0
+    }
+
+    if (detections.length === 1) {
+      // TypeScript doesn't infer that detections[0] exists after length check
+      // but we know it does, so we use non-null assertion safely
+      return detections[0]!.confidence
+    }
+
+    // Use complementary probability: 1 - (1-c1)*(1-c2)*...
+    // This properly accumulates risk from multiple detections
+    let complementaryProduct = 1
+    for (const detection of detections) {
+      complementaryProduct *= (1 - detection.confidence)
+    }
+
+    const aggregatedScore = 1 - complementaryProduct
+
+    // Ensure score is within bounds (should always be, but safety check)
+    return Math.max(0, Math.min(1, aggregatedScore))
+  }
+
+  /**
+   * Determines the recommended action based on the aggregated score
+   * 
+   * @param score - The aggregated risk score (0-1)
+   * @returns The recommended action
+   * 
+   * @private
+   */
+  private determineActionFromScore(score: RiskScore): AnomalyAction {
+    if (score >= 0.7) {
+      return 'BLOCK'
+    } else if (score >= 0.3) {
+      return 'WARN'
+    } else {
+      return 'ALLOW'
+    }
+  }
+
+  /**
+   * Returns true if any patterns were detected
+   * 
+   * @returns true if detections array has any items, false otherwise
+   * 
+   * @example
+   * ```typescript
+   * if (result.hasDetections()) {
+   *   console.log(`Found ${result.detections.length} prompt injection patterns`)
+   * }
+   * ```
+   */
+  hasDetections(): boolean {
+    return this.detected
+  }
+
+  /**
+   * Returns true if the action is BLOCK
+   * 
+   * @returns true if action is 'BLOCK', false otherwise
+   * 
+   * @example
+   * ```typescript
+   * if (result.shouldBlock()) {
+   *   // Handle blocking logic
+   * }
+   * ```
+   */
+  shouldBlock(): boolean {
+    return this.action === 'BLOCK'
+  }
+
+  /**
+   * Returns true if the action is WARN
+   * 
+   * @returns true if action is 'WARN', false otherwise
+   * 
+   * @example
+   * ```typescript
+   * if (result.shouldWarn()) {
+   *   // Log warning
+   * }
+   * ```
+   */
+  shouldWarn(): boolean {
+    return this.action === 'WARN'
+  }
+
+  /**
+   * Returns the number of detections found
+   * 
+   * @returns Count of individual detections
+   * 
+   * @example
+   * ```typescript
+   * const count = result.getDetectionCount()
+   * console.log(`Found ${count} prompt injection patterns`)
+   * ```
+   */
+  getDetectionCount(): number {
+    return this.detections.length
+  }
+
+  /**
+   * Returns all detections of a specific pattern type
+   * 
+   * @param pattern_type - The pattern type to filter by
+   * @returns Array of detections matching the pattern type
+   * 
+   * @example
+   * ```typescript
+   * const roleSwaps = result.getDetectionsByType('role_swapping')
+   * console.log(`Found ${roleSwaps.length} role swapping attempts`)
+   * ```
+   */
+  getDetectionsByType(pattern_type: string): readonly PiDetection[] {
+    return this.detections.filter(detection => detection.pattern_type === pattern_type)
+  }
+
+  /**
+   * Returns the highest confidence detection
+   * 
+   * @returns The detection with the highest confidence, or undefined if no detections
+   * 
+   * @example
+   * ```typescript
+   * const mostConfident = result.getHighestConfidenceDetection()
+   * if (mostConfident) {
+   *   console.log(`Most confident: ${mostConfident.pattern_type} (${mostConfident.confidence})`)
+   * }
+   * ```
+   */
+  getHighestConfidenceDetection(): PiDetection | undefined {
+    if (this.detections.length === 0) {
+      return undefined
+    }
+
+    return this.detections.reduce((highest, current) => {
+      return current.confidence > highest.confidence ? current : highest
+    })
+  }
+}

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

@@ -0,0 +1,151 @@
+import type {
+  BlockedIntent,
+  SensitiveScope,
+  ProtectedRole,
+  ImmutableInstruction
+} from '../../types'
+
+/**
+ * RoleProtection configuration for policy rules
+ * 
+ * @property protectedRoles - Array of roles that cannot be overridden
+ * @property immutableInstructions - Array of instructions that cannot be modified
+ */
+export interface RoleProtectionConfig {
+  readonly protectedRoles: readonly ProtectedRole[]
+  readonly immutableInstructions: readonly ImmutableInstruction[]
+}
+
+/**
+ * ContextLeakPrevention configuration for policy rules
+ * 
+ * @property enabled - Whether context leak prevention is enabled
+ * @property blockMetadataExposure - Whether to block metadata exposure
+ * @property sanitizeInternalReferences - Whether to sanitize internal references
+ */
+export interface ContextLeakPreventionConfig {
+  readonly enabled: boolean
+  readonly blockMetadataExposure: boolean
+  readonly sanitizeInternalReferences: boolean
+}
+
+/**
+ * PolicyRule value object represents a complete policy configuration
+ * 
+ * @property version - Policy version string
+ * @property blockedIntents - Array of intents that are explicitly blocked
+ * @property sensitiveScope - Array of sensitive topics requiring validation
+ * @property roleProtection - Configuration for role protection
+ * @property contextLeakPrevention - Configuration for context leak prevention
+ * 
+ * @example
+ * ```typescript
+ * const policy = new PolicyRule(
+ *   '1.0',
+ *   ['delete_user_data'],
+ *   ['financial_transactions'],
+ *   { protectedRoles: ['system'], immutableInstructions: [] },
+ *   { enabled: true, blockMetadataExposure: true, sanitizeInternalReferences: true }
+ * )
+ * ```
+ */
+export class PolicyRule {
+  readonly version: string
+  readonly blockedIntents: readonly BlockedIntent[]
+  readonly sensitiveScope: readonly SensitiveScope[]
+  readonly roleProtection: RoleProtectionConfig
+  readonly contextLeakPrevention: ContextLeakPreventionConfig
+
+  constructor(
+    version: string,
+    blockedIntents: BlockedIntent[],
+    sensitiveScope: SensitiveScope[],
+    roleProtection: RoleProtectionConfig,
+    contextLeakPrevention: ContextLeakPreventionConfig
+  ) {
+    if (!version || typeof version !== 'string' || version.trim().length === 0) {
+      throw new Error('PolicyRule version must be a non-empty string')
+    }
+
+    if (!Array.isArray(blockedIntents)) {
+      throw new Error('PolicyRule blockedIntents must be an array')
+    }
+
+    if (!Array.isArray(sensitiveScope)) {
+      throw new Error('PolicyRule sensitiveScope must be an array')
+    }
+
+    if (!roleProtection || typeof roleProtection !== 'object') {
+      throw new Error('PolicyRule roleProtection must be an object')
+    }
+
+    if (!Array.isArray(roleProtection.protectedRoles)) {
+      throw new Error('PolicyRule roleProtection.protectedRoles must be an array')
+    }
+
+    if (!Array.isArray(roleProtection.immutableInstructions)) {
+      throw new Error('PolicyRule roleProtection.immutableInstructions must be an array')
+    }
+
+    if (!contextLeakPrevention || typeof contextLeakPrevention !== 'object') {
+      throw new Error('PolicyRule contextLeakPrevention must be an object')
+    }
+
+    if (typeof contextLeakPrevention.enabled !== 'boolean') {
+      throw new Error('PolicyRule contextLeakPrevention.enabled must be a boolean')
+    }
+
+    if (typeof contextLeakPrevention.blockMetadataExposure !== 'boolean') {
+      throw new Error('PolicyRule contextLeakPrevention.blockMetadataExposure must be a boolean')
+    }
+
+    if (typeof contextLeakPrevention.sanitizeInternalReferences !== 'boolean') {
+      throw new Error('PolicyRule contextLeakPrevention.sanitizeInternalReferences must be a boolean')
+    }
+
+    this.version = version.trim()
+    this.blockedIntents = Object.freeze([...blockedIntents])
+    this.sensitiveScope = Object.freeze([...sensitiveScope])
+    this.roleProtection = {
+      protectedRoles: Object.freeze([...roleProtection.protectedRoles]),
+      immutableInstructions: Object.freeze([...roleProtection.immutableInstructions])
+    }
+    this.contextLeakPrevention = Object.freeze({ ...contextLeakPrevention })
+  }
+
+  /**
+   * Returns true if the given intent is blocked
+   */
+  isIntentBlocked(intent: string): boolean {
+    return this.blockedIntents.includes(intent)
+  }
+
+  /**
+   * Returns true if the given scope is sensitive
+   */
+  isScopeSensitive(scope: string): boolean {
+    return this.sensitiveScope.includes(scope)
+  }
+
+  /**
+   * Returns true if the given role is protected
+   */
+  isRoleProtected(role: string): boolean {
+    return this.roleProtection.protectedRoles.includes(role)
+  }
+
+  /**
+   * Returns true if the given instruction is immutable
+   */
+  isInstructionImmutable(instruction: string): boolean {
+    return this.roleProtection.immutableInstructions.includes(instruction)
+  }
+
+  /**
+   * Returns true if context leak prevention is enabled
+   */
+  isContextLeakPreventionEnabled(): boolean {
+    return this.contextLeakPrevention.enabled
+  }
+}
+

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

@@ -0,0 +1,34 @@
+import { TrustLevelType } from '../../types'
+
+
+/**
+ * TrustLevel value object represent the trust level of the content segment
+ * @props
+ *  - value: TrustLevelType
+ * @example
+ * ```typescript
+ * const trustLevel = new TrustLevel(TrustLevelType.TC)
+ * ```
+ */
+export class TrustLevel {
+  readonly value: TrustLevelType
+
+  constructor(value: TrustLevelType) {
+    if (!Object.values(TrustLevelType).includes(value)) {
+      throw new Error(`Invalid TrustLevel: ${value}`)
+    }
+    this.value = value
+  }
+
+  isTrusted(): boolean {
+    return this.value === TrustLevelType.TC
+  }
+
+  isSemiTrusted(): boolean {
+    return this.value === TrustLevelType.STC
+  }
+
+  isUntrusted(): boolean {
+    return this.value === TrustLevelType.UC
+  }
+}

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

@@ -0,0 +1,10 @@
+export * from './Origin'
+export * from './AnomalyScore'
+export * from './TrustLevel'
+export * from './LineageEntry'
+export * from './PiDetection'
+export * from './PiDetectionResult'
+export * from './ContentHash'
+export * from './PolicyRule'
+export * from './Origin-map'
+export * from './Pattern'

package/layers/csl/src/index.ts

@@ -0,0 +1,7 @@
+export * from './ports';
+export * from './types';
+export * from  './services';
+export * from './domain'
+export * from './adapters'
+
+

package/layers/csl/src/ports/index.ts

@@ -0,0 +1,10 @@
+export * from './output/DOMAdapter';
+export * from './output/Logger';
+export * from './output/HashGenerator';
+export * from './output/TimeStampProvider';
+export * from './output/PolicyRepository';
+export * from './output/SegmentClassified';
+
+// Input ports
+export * from './input/SegmentationPort';
+export * from './input/ClassificationPort';

package/layers/csl/src/ports/input/ClassificationPort.ts

@@ -0,0 +1,76 @@
+import type { Origin, TrustLevel } from '../../domain/value-objects';
+
+/**
+ * ClassificationPort is the input port for content classification that CSL exposes.
+ * 
+ * @remarks
+ * This port defines the contract for classifying content segments based on their origin.
+ * Classification determines the trust level (TC, STC, or UC) that should be assigned
+ * to a segment, which is a critical security decision in the CSL pipeline.
+ * 
+ * **Purpose:**
+ * - Defines the contract for origin-based trust classification
+ * - Enables consistent trust level assignment across the system
+ * - Allows implementation flexibility without affecting consumers
+ * 
+ * **Trust Level Classification:**
+ * - **TC (Trusted Content)**: Content from trusted sources (e.g., system-generated content)
+ * - **STC (Semi-Trusted Content)**: Content from partially trusted sources (e.g., visible DOM)
+ * - **UC (Untrusted Content)**: Content from untrusted sources (e.g., user input, hidden DOM)
+ * 
+ * **Classification Rules:**
+ * The classification logic maps Origin types to TrustLevel values based on security
+ * considerations. Different origins have different trustworthiness levels:
+ * - USER_INPUT → UC (always untrusted)
+ * - DOM_VISIBLE → STC (semi-trusted, visible to user)
+ * - DOM_HIDDEN → UC (untrusted, potentially malicious)
+ * - DOM_ATTRIBUTE → STC (semi-trusted, visible attributes)
+ * - SCRIPT_INJECTED → UC (untrusted, dynamically injected)
+ * - NETWORK_FETCHED → UC (untrusted, external source)
+ * - UNKNOWN → UC (untrusted, unknown origin)
+ * 
+ * **Implementation:**
+ * This interface is implemented by `OriginClassificationService` in the domain services layer.
+ * The service contains the business logic for mapping origins to trust levels.
+ * 
+ * @example
+ * ```typescript
+ * // Create a classification service that implements this port
+ * const classificationService: ClassificationPort = new ClassificationService()
+ * 
+ * // Classify a segment by its origin
+ * const origin = new Origin(OriginType.USER_INPUT)
+ * const trustLevel = classificationService.classify(origin)
+ * 
+ * // Use the trust level
+ * if (trustLevel.isUntrusted()) {
+ *   // Apply additional security measures
+ * }
+ * ```
+ */
+export interface ClassificationPort {
+    /**
+     * Classifies a content segment based on its origin and returns the appropriate trust level.
+     * 
+     * @param origin - The Origin value object representing where the content came from.
+     *                 This determines the trustworthiness of the content segment.
+     * 
+     * @returns The TrustLevel value object (TC, STC, or UC) that should be assigned
+     *          to the segment based on its origin. The trust level determines how the
+     *          segment will be handled in subsequent processing stages.
+     * 
+     * @example
+     * ```typescript
+     * // Classify user input (always untrusted)
+     * const userOrigin = new Origin(OriginType.USER_INPUT)
+     * const trustLevel = classificationPort.classify(userOrigin)
+     * // trustLevel.value === TrustLevelType.UC
+     * 
+     * // Classify visible DOM content (semi-trusted)
+     * const domOrigin = new Origin(OriginType.DOM_VISIBLE)
+     * const trustLevel = classificationPort.classify(domOrigin)
+     * // trustLevel.value === TrustLevelType.STC
+     * ```
+     */
+    classify(origin: Origin): TrustLevel;
+}

package/layers/csl/src/ports/input/SegmentationPort.ts

@@ -0,0 +1,81 @@
+import type { CSLResult } from '../../domain/entities/CSLResult';
+
+/**
+ * SegmentationPort is the main input port that CSL exposes to the external world.
+ * 
+ * @remarks
+ * This port defines the primary public API of the CSL (Context Segmentation Layer).
+ * It is implemented by the SegmentationService, which orchestrates the complete
+ * segmentation pipeline including DOM adaptation, normalization, classification,
+ * prompt injection detection, hashing, anomaly scoring, and lineage tracking.
+ * 
+ * **Purpose:**
+ * - Defines the contract for segmenting content from DOM elements or documents
+ * - Allows external consumers to process content through the CSL pipeline
+ * - Enables implementation flexibility without affecting consumers
+ * 
+ * **Processing Pipeline:**
+ * 1. Adapts DOM element/document to extract content segments
+ * 2. Normalizes segment content
+ * 3. Classifies segments by origin (assigns TrustLevel)
+ * 4. Detects prompt injection attempts
+ * 5. Generates cryptographic hashes
+ * 6. Calculates anomaly scores
+ * 7. Tracks lineage for auditability
+ * 8. Returns aggregated CSLResult with all processed segments
+ * 
+ * **Implementation:**
+ * This interface is implemented by `SegmentationService` in the services layer.
+ * The service coordinates domain services, adapters, and output ports to complete
+ * the segmentation process.
+ * 
+ * @example
+ * ```typescript
+ * // Create a segmentation service that implements this port
+ * const segmentationService: SegmentationPort = new SegmentationService(
+ *   domAdapter,
+ *   classificationService,
+ *   normalizationService,
+ *   // ... other dependencies
+ * )
+ * 
+ * // Process a DOM element
+ * const result = await segmentationService.segment(document.body)
+ * 
+ * // Access processed segments
+ * result.segments.forEach(segment => {
+ *   console.log(`Segment ${segment.id}: ${segment.trustLevel.value}`)
+ * })
+ * ```
+ */
+export interface SegmentationPort {
+    /**
+     * Segments content from a DOM element or document through the CSL processing pipeline.
+     * 
+     * @param element - The HTMLElement or Document to segment. Can be any DOM element
+     *                  (e.g., document.body, a specific div, input field) or the entire document.
+     * 
+     * @returns A Promise that resolves to a CSLResult containing:
+     *          - All processed segments with trust levels, hashes, and scores
+     *          - Aggregated metadata about the segmentation process
+     *          - Complete lineage entries for traceability
+     * 
+     * @throws {SegmentationError} If the segmentation process fails due to invalid input
+     *                             or processing errors
+     * 
+     * @example
+     * ```typescript
+     * // Segment the entire document
+     * const result = await segmentationPort.segment(document)
+     * 
+     * // Segment a specific element
+     * const formElement = document.getElementById('user-form')
+     * const result = await segmentationPort.segment(formElement)
+     * 
+     * // Process results
+     * console.log(`Processed ${result.metadata.total_segments} segments`)
+     * console.log(`Average anomaly score: ${result.metadata.anomaly_score}`)
+     * ```
+     */
+    segment(element: HTMLElement | Document): Promise<CSLResult>;
+}

package/layers/csl/src/ports/output/DOMAdapter.ts

@@ -0,0 +1,14 @@
+import type { RawDomPayload } from "../../types";
+
+
+/**
+ * DOMAdapterPort is the port for the DOMAdapter
+ * 
+ * @property adapt - Adapt the raw dom to the domain
+ * @property debug - Debug the raw dom and show it in the console
+ */
+export interface DOMAdapterPort {
+    adapt(): Promise<RawDomPayload>;
+    debug(payload: RawDomPayload): void;
+    // ... more methods to come
+}

package/layers/csl/src/ports/output/HashGenerator.ts

@@ -0,0 +1,18 @@
+
+
+/**
+ * HashGeneratorPort is the port for the hash generator
+ * @property generate - Generate a hash from the content
+ * @property compare - compare a content with a hash and return true if they are the same
+ * @property generateHMAC - Generate an HMAC hash from the content using a secret key
+ * @property compareHMAC - Compare a content with an HMAC hash using a secret key and return true if they are the same
+ */
+
+export type HashAlgorithm = 'sha1' | 'sha256' | 'sha512' | 'md5' | 'ripemd160';
+
+export interface HashGeneratorPort {
+    generate(content: string, algorithm?: HashAlgorithm): Promise<string>;
+    compare(content: string, hash: string, algorithm?: HashAlgorithm): Promise<boolean>;
+    generateHMAC(content: string, secretKey: string, algorithm?: HashAlgorithm): Promise<string>;
+    compareHMAC(content: string, hash: string, secretKey: string, algorithm?: HashAlgorithm): Promise<boolean>;
+}