@ai-pip/csl 0.1.3 → 0.1.5

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

@@ -0,0 +1,54 @@
+import type { CSLHashAlgorithm } from "../../types";
+
+/**
+ * ContentHash value object represents a cryptographic hash of content
+ * 
+ * @property value - The hash value as a hexadecimal string
+ * @property algorithm - The hash algorithm used (sha256 or sha512)
+ * 
+ * @example
+ * ```typescript
+ * const hash = new ContentHash('a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3', 'sha256')
+ * ```
+ */
+export class ContentHash {
+  readonly value: string
+  readonly algorithm: CSLHashAlgorithm
+
+  constructor(value: string, algorithm: CSLHashAlgorithm = 'sha256') {
+    if (!value || typeof value !== 'string') {
+      throw new Error('ContentHash value must be a non-empty string')
+    }
+
+    if (!['sha256', 'sha512'].includes(algorithm)) {
+      throw new Error(`Invalid HashAlgorithm: ${algorithm}. Must be 'sha256' or 'sha512'`)
+    }
+
+    const hexPattern = /^[a-f0-9]+$/i
+    if (!hexPattern.test(value)) {
+      throw new Error('ContentHash value must be a valid hexadecimal string')
+    }
+
+    const expectedLength = algorithm === 'sha256' ? 64 : 128
+    if (value.length !== expectedLength) {
+      throw new Error(`ContentHash value length must be ${expectedLength} characters for ${algorithm}`)
+    }
+
+    this.value = value.toLowerCase()
+    this.algorithm = algorithm
+  }
+
+  /**
+   * Returns true if the hash uses SHA-256 algorithm
+   */
+  isSha256(): boolean {
+    return this.algorithm === 'sha256'
+  }
+
+  /**
+   * Returns true if the hash uses SHA-512 algorithm
+   */
+  isSha512(): boolean {
+    return this.algorithm === 'sha512'
+  }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * LineageEntry value object represents a single entry in the lineage chain of a content segment
+ * 
+ * @property step - Description of the processing step
+ * @property timestamp - Unix timestamp in milliseconds
+ * @property notes - Optional additional notes about this step
+ * 
+ * @example
+ * ```typescript
+ * const entry = new LineageEntry('normalization', Date.now(), 'Unicode normalization applied')
+ * ```
+ */
+export class LineageEntry {
+  readonly step: string
+  readonly timestamp: number
+  readonly notes?: string
+
+  constructor(step: string, timestamp: number, notes?: string) {
+    if (!step || typeof step !== 'string' || step.trim().length === 0) {
+      throw new Error('LineageEntry step must be a non-empty string')
+    }
+
+    if (typeof timestamp !== 'number' || timestamp < 0 || !Number.isFinite(timestamp)) {
+      throw new Error('LineageEntry timestamp must be a valid positive number')
+    }
+
+    if (notes !== undefined && (typeof notes !== 'string' || notes.trim().length === 0)) {
+      throw new Error('LineageEntry notes must be a non-empty string if provided')
+    }
+
+    this.step = step.trim()
+    this.timestamp = timestamp
+    this.notes = notes?.trim() ?? ''
+  }
+
+  /**
+   * Returns true if this entry has notes
+   */
+  hasNotes(): boolean {
+    return this.notes !== undefined && this.notes.length > 0
+  }
+}

package/layers/csl/src/domain/value-objects/Origin-map.ts

@@ -0,0 +1,67 @@
+import { OriginType, TrustLevelType } from "../../types";
+
+
+
+/**
+ * originMap is the deterministic mapping from OriginType to TrustLevelType.
+ * 
+ * @remarks
+ * This map defines the **deterministic classification rules** for content segments.
+ * The mapping is based solely on the origin type, not on content analysis.
+ * 
+ * **Key Principles:**
+ * - 100% deterministic: same origin → same trust level, always
+ * - No heuristics or content analysis
+ * - All OriginType values must be present in this map
+ * - Future content analysis can be added as a separate layer
+ * 
+ * **Mapping Rules:**
+ * - USER → UC (always untrusted for security)
+ * - DOM_VISIBLE → STC (user can verify)
+ * - DOM_HIDDEN → UC (potential attack vector)
+ * - DOM_ATTRIBUTE → STC (visible in source)
+ * - SCRIPT_INJECTED → UC (can be manipulated)
+ * - NETWORK_FETCHED → UC (external source)
+ * - SYSTEM_GENERATED → TC (system controls it)
+ * - UNKNOWN → UC (unknown is untrusted by default)
+ */
+export const originMap = new Map<OriginType, TrustLevelType>([
+    // User origins - always untrusted (security by default)
+    [OriginType.USER, TrustLevelType.UC],
+    
+    // DOM origins - trust based on visibility
+    [OriginType.DOM_VISIBLE, TrustLevelType.STC],
+    [OriginType.DOM_HIDDEN, TrustLevelType.UC],
+    [OriginType.DOM_ATTRIBUTE, TrustLevelType.STC],
+    
+    // External origins - always untrusted
+    [OriginType.SCRIPT_INJECTED, TrustLevelType.UC],
+    [OriginType.NETWORK_FETCHED, TrustLevelType.UC],
+    
+    // System origins - trusted (system controls)
+    [OriginType.SYSTEM_GENERATED, TrustLevelType.TC],
+    
+    // Unknown - untrusted by default (fail-secure)
+    [OriginType.UNKNOWN, TrustLevelType.UC],
+]);
+
+/**
+ * Validates that all OriginType values are mapped in originMap.
+ * 
+ * @remarks
+ * This function ensures completeness of the mapping at runtime.
+ * Throws an error if any OriginType is missing from the map.
+ * 
+ * @throws {Error} If any OriginType is not present in originMap
+ */
+export function validateOriginMap(): void {
+    const allOriginTypes = Object.values(OriginType);
+    const missingTypes = allOriginTypes.filter(type => !originMap.has(type));
+    
+    if (missingTypes.length > 0) {
+        throw new Error(
+            `Missing origin mappings: ${missingTypes.join(', ')}. ` +
+            `All OriginType values must be mapped in originMap.`
+        );
+    }
+}

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

@@ -0,0 +1,99 @@
+import { OriginType } from '../../types'
+
+
+/**
+ * Origin value object represents the deterministic source of a content segment.
+ * 
+ * @remarks
+ * Origin is a value object that encapsulates the source type of content.
+ * The origin type determines the trust level through deterministic classification.
+ * 
+ * **Deterministic Classification:**
+ * - Classification is based solely on the origin type
+ * - No content analysis or heuristics
+ * - 100% reproducible: same origin → same trust level
+ * 
+ * @property type - The origin type (USER, DOM_VISIBLE, DOM_HIDDEN, etc.)
+ * 
+ * @example
+ * ```typescript
+ * // Create origin for user input
+ * const userOrigin = new Origin(OriginType.USER)
+ * 
+ * // Check origin characteristics
+ * if (userOrigin.isUser()) {
+ *   // Handle user input with extra security
+ * }
+ * 
+ * // Create origin for system content
+ * const systemOrigin = new Origin(OriginType.SYSTEM_GENERATED)
+ * if (systemOrigin.isSystem()) {
+ *   // Handle system content with trust
+ * }
+ * ```
+ */
+
+
+export class Origin {
+    readonly type: OriginType;
+
+    constructor(type: OriginType){
+        if(!Object.values(OriginType).includes(type)){
+            throw new Error(`Invalid Origin type: ${type}`)
+        }
+        this.type = type
+    }
+
+    /**
+     * Checks if the origin is from DOM (visible, hidden, or attribute)
+     */
+    isDom(): boolean {
+        return this.type === OriginType.DOM_HIDDEN ||
+               this.type === OriginType.DOM_VISIBLE ||
+               this.type === OriginType.DOM_ATTRIBUTE
+    }
+
+    /**
+     * Checks if the origin is direct user input
+     */
+    isUser(): boolean {
+        return this.type === OriginType.USER
+    }
+
+    /**
+     * Checks if the origin is system-generated content
+     */
+    isSystem(): boolean {
+        return this.type === OriginType.SYSTEM_GENERATED
+    }
+
+    /**
+     * Checks if the origin is script-injected content
+     */
+    isInjected(): boolean {
+        return this.type === OriginType.SCRIPT_INJECTED
+    }
+
+    /**
+     * Checks if the origin is unknown
+     */
+    isUnknown(): boolean {
+        return this.type === OriginType.UNKNOWN
+    }
+
+    /**
+     * Checks if the origin is network-fetched content
+     */
+    isNetworkFetched(): boolean {
+        return this.type === OriginType.NETWORK_FETCHED
+    }
+
+    /**
+     * Checks if the origin is from an external source (network or injected)
+     */
+    isExternal(): boolean {
+        return this.type === OriginType.NETWORK_FETCHED ||
+               this.type === OriginType.SCRIPT_INJECTED
+    }
+
+}

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

@@ -0,0 +1,221 @@
+import type { RiskScore } from '../../types'
+import { PatternHelpers } from '../../utils/pattern-helpers'
+
+/**
+ * Pattern value object represents a detection pattern for prompt injection attacks
+ * 
+ * @remarks
+ * Patterns define how to detect specific types of prompt injection attempts.
+ * They can be created from regular expression strings or RegExp objects.
+ * The pattern is normalized to a RegExp internally for consistent matching.
+ * 
+ * **Key Features:**
+ * - Normalizes regex strings to RegExp objects
+ * - Maintains immutability through Object.freeze
+ * - Provides methods for pattern matching and match information extraction
+ * - Validates all inputs to ensure pattern integrity
+ * 
+ * **Usage:**
+ * Patterns are typically used by PiDetectionService to scan content for malicious patterns.
+ * Each pattern has a base confidence score that can be adjusted based on context.
+ * 
+ * @property pattern_type - Type of pattern (e.g., "role_swapping", "instruction_override")
+ * @property regex - Compiled regular expression for pattern matching (always RegExp after construction)
+ * @property base_confidence - Base confidence score for this pattern (0-1)
+ * @property description - Optional description of what this pattern detects
+ * 
+ * @example
+ * ```typescript
+ * // Create pattern from string
+ * const pattern = new Pattern(
+ *   'role_swapping',
+ *   'you are no longer',
+ *   0.9,
+ *   'Detects attempts to change AI role'
+ * )
+ * 
+ * // Create pattern from RegExp
+ * const pattern2 = new Pattern(
+ *   'instruction_override',
+ *   /ignore\s+(all\s+)?(previous|prior)\s+instructions?/i,
+ *   0.95
+ * )
+ * 
+ * // Check if pattern matches content
+ * if (pattern.matches(content)) {
+ *   const match = pattern.findMatch(content)
+ *   if (match) {
+ *     // Use match information to create PiDetection
+ *   }
+ * }
+ * ```
+ */
+export class Pattern {
+  readonly pattern_type: string
+  readonly regex: RegExp
+  readonly base_confidence: RiskScore
+  readonly description: string
+
+  constructor(
+    pattern_type: string,
+    regex: string | RegExp,
+    base_confidence: RiskScore,
+    description?: string
+  ) {
+    // Validate all inputs using helper functions
+    PatternHelpers.validatePatternType(pattern_type)
+    PatternHelpers.validateRegex(regex)
+    PatternHelpers.validateBaseConfidence(base_confidence)
+    PatternHelpers.validateDescription(description)
+
+    this.pattern_type = pattern_type.trim()
+
+    // Validate and process regex
+    const regexSource = typeof regex === 'string' ? regex : regex.source
+    PatternHelpers.validateRegexLength(regexSource)
+    PatternHelpers.checkForReDoSPatterns(regexSource, this.pattern_type)
+
+    // Normalize regex to RegExp for consistency and immutability
+    this.regex = typeof regex === 'string'
+      ? PatternHelpers.compileRegexString(regex)
+      : PatternHelpers.cloneRegExp(regex)
+
+    this.base_confidence = base_confidence
+    this.description = description?.trim() ?? ''
+
+    // Freeze the object for immutability
+    Object.freeze(this)
+  }
+
+  /**
+   * Checks if the pattern matches the given content
+   * 
+   * @param content - The content string to test against the pattern
+   * @returns true if the pattern matches, false otherwise
+   * 
+   * @throws {TypeError} If content is not a valid non-empty string
+   * 
+   * @example
+   * ```typescript
+   * const pattern = new Pattern('role_swapping', 'you are no longer', 0.9)
+   * if (pattern.matches('Hello, you are no longer an AI')) {
+   *   // Pattern detected
+   * }
+   * ```
+   */
+  matches(content: string): boolean {
+    PatternHelpers.validateContent(content, 'matches')
+    PatternHelpers.validateContentLength(content, 'matches')
+    return this.regex.test(content)
+  }
+
+  /**
+   * Finds the first match in content and returns match information
+   * 
+   * @remarks
+   * This method is useful when you need to create a PiDetection from a pattern match.
+   * It returns the exact matched text and its position in the content.
+   * 
+   * @param content - The content string to search for matches
+   * @returns Match information with matched text and position, or null if no match found
+   * 
+   * @throws {TypeError} If content is not a valid non-empty string
+   * 
+   * @example
+   * ```typescript
+   * const pattern = new Pattern('role_swapping', 'you are no longer', 0.9)
+   * const match = pattern.findMatch('Hello, you are no longer an AI assistant')
+   * 
+   * if (match) {
+   *   // match.matched = 'you are no longer'
+   *   // match.position = { start: 7, end: 25 }
+   *   const detection = new PiDetection(
+   *     pattern.pattern_type,
+   *     match.matched,
+   *     match.position,
+   *     pattern.base_confidence
+   *   )
+   * }
+   * ```
+   */
+  findMatch(content: string): { matched: string; position: { start: number; end: number } } | null {
+    PatternHelpers.validateContent(content, 'findMatch')
+    PatternHelpers.validateContentLength(content, 'findMatch')
+
+    const match = this.regex.exec(content)
+    if (!match) {
+      return null
+    }
+
+    return PatternHelpers.createMatchResult(match)
+  }
+
+  /**
+   * Finds all matches in content and returns match information for each
+   * 
+   * @remarks
+   * This method finds all non-overlapping matches of the pattern in the content.
+   * Useful when a pattern might appear multiple times in the same content.
+   * 
+   * @param content - The content string to search for matches
+   * @returns Array of match information, empty array if no matches found
+   * 
+   * @throws {TypeError} If content is not a valid non-empty string
+   * 
+   * @example
+   * ```typescript
+   * const pattern = new Pattern('instruction_override', 'ignore', 0.9)
+   * const matches = pattern.findAllMatches('ignore this and ignore that')
+   * // Returns: [
+   * //   { matched: 'ignore', position: { start: 0, end: 6 } },
+   * //   { matched: 'ignore', position: { start: 20, end: 26 } }
+   * // ]
+   * ```
+   */
+  findAllMatches(content: string): Array<{ matched: string; position: { start: number; end: number } }> {
+    PatternHelpers.validateContent(content, 'findAllMatches')
+    PatternHelpers.validateContentLength(content, 'findAllMatches')
+
+    const matches: Array<{ matched: string; position: { start: number; end: number } }> = []
+    const globalRegex = new RegExp(this.regex.source, this.regex.flags + 'g')
+    let match: RegExpExecArray | null
+    let iterations = 0
+
+    while ((match = globalRegex.exec(content)) !== null) {
+      iterations++
+
+      if (PatternHelpers.checkMatchLimits(matches.length, iterations)) {
+        break
+      }
+
+      matches.push(PatternHelpers.createMatchResult(match))
+      PatternHelpers.handleEmptyStringMatch(globalRegex, match)
+    }
+
+    return matches
+  }
+
+  /**
+   * Returns the base confidence score for this pattern
+   * 
+   * @returns The base confidence score (0-1)
+   * 
+   * @example
+   * ```typescript
+   * const pattern = new Pattern('role_swapping', 'you are no longer', 0.9)
+   * const confidence = pattern.getConfidence() // Returns: 0.9
+   * ```
+   */
+  getConfidence(): RiskScore {
+    return this.base_confidence
+  }
+
+  /**
+   * Returns true if this pattern has a description
+   * 
+   * @returns true if description is not empty, false otherwise
+   */
+  hasDescription(): boolean {
+    return this.description.length > 0
+  }
+}

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

@@ -0,0 +1,140 @@
+import type { RiskScore } from '../../types'
+
+/**
+ * Position represents the location of a detected pattern within content
+ * 
+ * @property start - Start position (inclusive, 0-based index)
+ * @property end - End position (exclusive, 0-based index)
+ * 
+ * @example
+ * ```typescript
+ * const position = { start: 12, end: 35 }
+ * // This means the pattern spans from character 12 to 34 (inclusive)
+ * ```
+ */
+export interface Position {
+  readonly start: number
+  readonly end: number
+}
+
+/**
+ * PiDetection value object represents a single prompt injection detection
+ * 
+ * @remarks
+ * This value object encapsulates all information about a single detected pattern:
+ * - What type of pattern was detected
+ * - The exact text that matched
+ * - Where it was found in the content
+ * - How confident the detection is
+ * 
+ * **Immutability:**
+ * All properties are readonly and the object is frozen to ensure immutability.
+ * 
+ * @property pattern_type - Type of malicious pattern detected (e.g., "role_swapping", "instruction_override")
+ * @property matched_pattern - The exact text that matched the pattern
+ * @property position - Location of the pattern in the content (start and end indices)
+ * @property confidence - Confidence score for this specific detection (0-1)
+ * 
+ * @example
+ * ```typescript
+ * const detection = new PiDetection(
+ *   'role_swapping',
+ *   'you are no longer an AI assistant',
+ *   { start: 12, end: 47 },
+ *   0.95
+ * )
+ * ```
+ */
+export class PiDetection {
+  readonly pattern_type: string
+  readonly matched_pattern: string
+  readonly position: Position
+  readonly confidence: RiskScore
+
+  constructor(
+    pattern_type: string,
+    matched_pattern: string,
+    position: Position,
+    confidence: RiskScore
+  ) {
+    // Validate pattern_type
+    if (!pattern_type || typeof pattern_type !== 'string' || pattern_type.trim().length === 0) {
+      throw new Error('PiDetection pattern_type must be a non-empty string')
+    }
+
+    // Validate matched_pattern
+    if (!matched_pattern || typeof matched_pattern !== 'string') {
+      throw new Error('PiDetection matched_pattern must be a non-empty string')
+    }
+
+    // Validate position
+    if (!position || typeof position !== 'object') {
+      throw new TypeError('PiDetection position must be an object with start and end properties')
+    }
+
+    if (typeof position.start !== 'number' || !Number.isFinite(position.start) || position.start < 0) {
+      throw new Error('PiDetection position.start must be a valid non-negative number')
+    }
+
+    if (typeof position.end !== 'number' || !Number.isFinite(position.end) || position.end < 0) {
+      throw new Error('PiDetection position.end must be a valid non-negative number')
+    }
+
+    if (position.end <= position.start) {
+      throw new Error('PiDetection position.end must be greater than position.start')
+    }
+
+    // Validate confidence
+    if (typeof confidence !== 'number' || !Number.isFinite(confidence)) {
+      throw new TypeError('PiDetection confidence must be a valid number')
+    }
+
+    if (confidence < 0 || confidence > 1) {
+      throw new Error('PiDetection confidence must be between 0 and 1')
+    }
+
+    // Validate that matched_pattern length matches position
+    const patternLength = position.end - position.start
+    if (matched_pattern.length !== patternLength) {
+      throw new Error(
+        `PiDetection matched_pattern length (${matched_pattern.length}) does not match position range (${patternLength})`
+      )
+    }
+
+    this.pattern_type = pattern_type.trim()
+    this.matched_pattern = matched_pattern
+    this.position = Object.freeze({ ...position })
+    this.confidence = confidence
+
+    // Freeze the entire object for immutability
+    Object.freeze(this)
+  }
+
+  /**
+   * Returns the length of the detected pattern
+   */
+  getLength(): number {
+    return this.position.end - this.position.start
+  }
+
+  /**
+   * Returns true if this detection has high confidence (>= 0.7)
+   */
+  isHighConfidence(): boolean {
+    return this.confidence >= 0.7
+  }
+
+  /**
+   * Returns true if this detection has medium confidence (>= 0.3 and < 0.7)
+   */
+  isMediumConfidence(): boolean {
+    return this.confidence >= 0.3 && this.confidence < 0.7
+  }
+
+  /**
+   * Returns true if this detection has low confidence (< 0.3)
+   */
+  isLowConfidence(): boolean {
+    return this.confidence < 0.3
+  }
+}