@ai-pip/csl 0.1.0 → 0.1.3

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

@@ -1,275 +0,0 @@
-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/domain/value-objects/PolicyRule.ts

@@ -1,151 +0,0 @@
-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/domain/value-objects/TrustLevel.ts

@@ -1,34 +0,0 @@
-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/domain/value-objects/index.ts

@@ -1,10 +0,0 @@
-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/index.ts

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

package/layers/csl/ports/index.ts

@@ -1,10 +0,0 @@
-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/ports/input/ClassificationPort.ts

@@ -1,76 +0,0 @@
-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/ports/input/SegmentationPort.ts

@@ -1,81 +0,0 @@
-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/ports/output/DOMAdapter.ts

@@ -1,14 +0,0 @@
-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/ports/output/HashGenerator.ts

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