@ai-pip/core 0.1.0

package/src/isl/value-objects/Pattern.ts

@@ -0,0 +1,158 @@
+import type { RiskScore } from '../types'
+
+/**
+ * Pattern - tipo puro
+ */
+export type Pattern = {
+  readonly pattern_type: string
+  readonly regex: RegExp
+  readonly base_confidence: RiskScore
+  readonly description: string
+}
+
+/**
+ * Constantes de seguridad para pattern matching
+ */
+export const MAX_CONTENT_LENGTH = 10_000_000 // 10MB
+export const MAX_PATTERN_LENGTH = 10_000
+export const MAX_MATCHES = 10_000
+
+/**
+ * Valida pattern_type - función pura
+ */
+function validatePatternType(pattern_type: unknown): asserts pattern_type is string {
+  if (!pattern_type || typeof pattern_type !== 'string' || pattern_type.trim().length === 0) {
+    throw new TypeError('Pattern pattern_type must be a non-empty string')
+  }
+}
+
+/**
+ * Valida regex - función pura
+ */
+function validateRegex(regex: unknown): asserts regex is string | RegExp {
+  if (!regex || (typeof regex !== 'string' && !(regex instanceof RegExp))) {
+    throw new TypeError('Pattern regex must be a string or a RegExp')
+  }
+}
+
+/**
+ * Valida base_confidence - función pura
+ */
+function validateBaseConfidence(base_confidence: unknown): asserts base_confidence is number {
+  if (typeof base_confidence !== 'number' || !Number.isFinite(base_confidence)) {
+    throw new TypeError('Pattern base_confidence must be a valid number')
+  }
+
+  if (base_confidence < 0 || base_confidence > 1) {
+    throw new Error('Pattern base_confidence must be between 0 and 1')
+  }
+}
+
+/**
+ * Valida description - función pura
+ */
+function validateDescription(description: unknown): void {
+  if (description !== undefined && (typeof description !== 'string' || description.trim().length === 0)) {
+    throw new TypeError('Pattern description must be a non-empty string if provided')
+  }
+}
+
+/**
+ * Compila regex string a RegExp - función pura
+ */
+function compileRegexString(regex: string): RegExp {
+  try {
+    return new RegExp(regex, 'i')
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    throw new TypeError(`Pattern regex must be a valid regular expression: ${regex}. Original error: ${errorMessage}`)
+  }
+}
+
+/**
+ * Clona RegExp - función pura
+ */
+function cloneRegExp(regex: RegExp): RegExp {
+  return new RegExp(regex.source, regex.flags)
+}
+
+/**
+ * Crea un Pattern - función pura
+ */
+export function createPattern(
+  pattern_type: string,
+  regex: string | RegExp,
+  base_confidence: RiskScore,
+  description?: string
+): Pattern {
+  // Validar inputs
+  validatePatternType(pattern_type)
+  validateRegex(regex)
+  validateBaseConfidence(base_confidence)
+  validateDescription(description)
+
+  // Validar y procesar regex
+  const regexSource = typeof regex === 'string' ? regex : regex.source
+  
+  if (regexSource.length > MAX_PATTERN_LENGTH) {
+    throw new Error(`Pattern regex source exceeds maximum length of ${MAX_PATTERN_LENGTH} characters`)
+  }
+
+  // Normalizar regex a RegExp
+  const normalizedRegex = typeof regex === 'string'
+    ? compileRegexString(regex)
+    : cloneRegExp(regex)
+
+  return {
+    pattern_type: pattern_type.trim(),
+    regex: normalizedRegex,
+    base_confidence,
+    description: description?.trim() ?? ''
+  }
+}
+
+/**
+ * Funciones puras para Pattern matching
+ */
+export function matchesPattern(pattern: Pattern, content: string): boolean {
+  if (!content || typeof content !== 'string') {
+    throw new TypeError('Pattern.matches: content must be a non-empty string')
+  }
+
+  if (content.length > MAX_CONTENT_LENGTH) {
+    throw new Error(
+      `Pattern.matches: Content length (${content.length}) exceeds maximum allowed length (${MAX_CONTENT_LENGTH})`
+    )
+  }
+
+  return pattern.regex.test(content)
+}
+
+export function findMatch(pattern: Pattern, content: string): {
+  matched: string
+  position: { start: number; end: number }
+} | null {
+  if (!content || typeof content !== 'string') {
+    throw new TypeError('Pattern.findMatch: content must be a non-empty string')
+  }
+
+  if (content.length > MAX_CONTENT_LENGTH) {
+    throw new Error(
+      `Pattern.findMatch: Content length (${content.length}) exceeds maximum allowed length (${MAX_CONTENT_LENGTH})`
+    )
+  }
+
+  const match = pattern.regex.exec(content)
+  if (match?.index === undefined) {
+    return null
+  }
+
+  return {
+    matched: match[0],
+    position: {
+      start: match.index,
+      end: match.index + match[0].length
+    }
+  }
+}
+

package/src/isl/value-objects/PiDetection.ts

@@ -0,0 +1,92 @@
+import type { Position, RiskScore } from '../types'
+
+/**
+ * PiDetection - tipo puro
+ */
+export type PiDetection = {
+  readonly pattern_type: string
+  readonly matched_pattern: string
+  readonly position: Position
+  readonly confidence: RiskScore
+}
+
+/**
+ * Crea un PiDetection - función pura
+ */
+export function createPiDetection(
+  pattern_type: string,
+  matched_pattern: string,
+  position: Position,
+  confidence: RiskScore
+): PiDetection {
+  // Validar 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')
+  }
+
+  // Validar matched_pattern
+  if (!matched_pattern || typeof matched_pattern !== 'string') {
+    throw new Error('PiDetection matched_pattern must be a non-empty string')
+  }
+
+  // Validar 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')
+  }
+
+  // Validar 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')
+  }
+
+  // Validar que matched_pattern length coincide con 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})`
+    )
+  }
+
+  return {
+    pattern_type: pattern_type.trim(),
+    matched_pattern,
+    position: Object.freeze({ ...position }),
+    confidence
+  }
+}
+
+/**
+ * Funciones puras para PiDetection
+ */
+export function getDetectionLength(detection: PiDetection): number {
+  return detection.position.end - detection.position.start
+}
+
+export function isHighConfidence(detection: PiDetection): boolean {
+  return detection.confidence >= 0.7
+}
+
+export function isMediumConfidence(detection: PiDetection): boolean {
+  return detection.confidence >= 0.3 && detection.confidence < 0.7
+}
+
+export function isLowConfidence(detection: PiDetection): boolean {
+  return detection.confidence < 0.3
+}
+

package/src/isl/value-objects/PiDetectionResult.ts

@@ -0,0 +1,129 @@
+import type { AnomalyAction, RiskScore } from '../types'
+import type { PiDetection } from './PiDetection'
+
+/**
+ * PiDetectionResult - tipo puro
+ */
+export type PiDetectionResult = {
+  readonly detections: readonly PiDetection[]
+  readonly score: RiskScore
+  readonly action: AnomalyAction
+  readonly patterns: readonly string[]
+  readonly detected: boolean
+}
+
+/**
+ * Calcula score agregado desde detecciones individuales - función pura
+ */
+function calculateAggregatedScore(detections: readonly PiDetection[]): RiskScore {
+  if (detections.length === 0) {
+    return 0
+  }
+
+  if (detections.length === 1) {
+    const first = detections[0]
+    if (!first) return 0
+    return first.confidence
+  }
+
+  // Usar probabilidad complementaria: 1 - (1-c1)*(1-c2)*...
+  let complementaryProduct = 1
+  for (const detection of detections) {
+    complementaryProduct *= (1 - detection.confidence)
+  }
+
+  const aggregatedScore = 1 - complementaryProduct
+  return Math.max(0, Math.min(1, aggregatedScore))
+}
+
+/**
+ * Determina acción basada en score - función pura
+ */
+function determineActionFromScore(score: RiskScore): AnomalyAction {
+  if (score >= 0.7) {
+    return 'BLOCK'
+  } else if (score >= 0.3) {
+    return 'WARN'
+  } else {
+    return 'ALLOW'
+  }
+}
+
+/**
+ * Crea un PiDetectionResult - función pura
+ */
+export function createPiDetectionResult(
+  detections: readonly PiDetection[],
+  action?: AnomalyAction
+): PiDetectionResult {
+  // Validar detections array
+  if (!Array.isArray(detections)) {
+    throw new TypeError('PiDetectionResult detections must be an array')
+  }
+
+  // Calcular score agregado
+  const score = calculateAggregatedScore(detections)
+
+  // Determinar acción (o usar la proporcionada)
+  const finalAction = action ?? determineActionFromScore(score)
+
+  // Validar acción
+  if (!['ALLOW', 'WARN', 'BLOCK'].includes(finalAction)) {
+    throw new Error(`Invalid AnomalyAction: ${finalAction}. Must be one of: ALLOW, WARN, BLOCK`)
+  }
+
+  // Validar que la acción coincide con el score calculado
+  const expectedAction = determineActionFromScore(score)
+  if (finalAction !== expectedAction) {
+    throw new Error(
+      `PiDetectionResult action mismatch. Calculated score ${score} requires action '${expectedAction}', but '${finalAction}' was provided`
+    )
+  }
+
+  // Derivar patterns array
+  const patterns: readonly string[] = detections.map((detection: PiDetection) => detection.pattern_type)
+
+  const result: PiDetectionResult = {
+    detections: Object.freeze(Array.from(detections)) as readonly PiDetection[],
+    score,
+    action: finalAction,
+    patterns: Object.freeze(Array.from(patterns)),
+    detected: detections.length > 0
+  }
+  
+  return result
+}
+
+/**
+ * Funciones puras para PiDetectionResult
+ */
+export function hasDetections(result: PiDetectionResult): boolean {
+  return result.detected
+}
+
+// shouldBlock y shouldWarn NO son core - son decisiones que van a ModelGateway
+// El core solo produce señales (score, action), no decide acciones finales
+
+export function getDetectionCount(result: PiDetectionResult): number {
+  return result.detections.length
+}
+
+export function getDetectionsByType(
+  result: PiDetectionResult,
+  pattern_type: string
+): readonly PiDetection[] {
+  return result.detections.filter(detection => detection.pattern_type === pattern_type)
+}
+
+export function getHighestConfidenceDetection(
+  result: PiDetectionResult
+): PiDetection | undefined {
+  if (result.detections.length === 0) {
+    return undefined
+  }
+
+  return result.detections.reduce((highest, current) => {
+    return current.confidence > highest.confidence ? current : highest
+  })
+}
+

package/src/isl/value-objects/PolicyRule.ts

@@ -0,0 +1,117 @@
+import type { BlockedIntent, ImmutableInstruction, ProtectedRole, SensitiveScope } from '../types'
+
+/**
+ * RoleProtectionConfig - configuración de protección de roles
+ */
+export type RoleProtectionConfig = {
+  readonly protectedRoles: readonly ProtectedRole[]
+  readonly immutableInstructions: readonly ImmutableInstruction[]
+}
+
+/**
+ * ContextLeakPreventionConfig - configuración de prevención de fuga de contexto
+ */
+export type ContextLeakPreventionConfig = {
+  readonly enabled: boolean
+  readonly blockMetadataExposure: boolean
+  readonly sanitizeInternalReferences: boolean
+}
+
+/**
+ * PolicyRule - tipo puro
+ */
+export type PolicyRule = {
+  readonly version: string
+  readonly blockedIntents: readonly BlockedIntent[]
+  readonly sensitiveScope: readonly SensitiveScope[]
+  readonly roleProtection: RoleProtectionConfig
+  readonly contextLeakPrevention: ContextLeakPreventionConfig
+}
+
+/**
+ * Crea un PolicyRule - función pura
+ */
+export function createPolicyRule(
+  version: string,
+  blockedIntents: readonly BlockedIntent[],
+  sensitiveScope: readonly SensitiveScope[],
+  roleProtection: RoleProtectionConfig,
+  contextLeakPrevention: ContextLeakPreventionConfig
+): PolicyRule {
+  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 TypeError('PolicyRule blockedIntents must be an array')
+  }
+
+  if (!Array.isArray(sensitiveScope)) {
+    throw new TypeError('PolicyRule sensitiveScope must be an array')
+  }
+
+  if (!roleProtection || typeof roleProtection !== 'object') {
+    throw new TypeError('PolicyRule roleProtection must be an object')
+  }
+
+  if (!Array.isArray(roleProtection.protectedRoles)) {
+    throw new TypeError('PolicyRule roleProtection.protectedRoles must be an array')
+  }
+
+  if (!Array.isArray(roleProtection.immutableInstructions)) {
+    throw new TypeError('PolicyRule roleProtection.immutableInstructions must be an array')
+  }
+
+  if (!contextLeakPrevention || typeof contextLeakPrevention !== 'object') {
+    throw new TypeError('PolicyRule contextLeakPrevention must be an object')
+  }
+
+  if (typeof contextLeakPrevention.enabled !== 'boolean') {
+    throw new TypeError('PolicyRule contextLeakPrevention.enabled must be a boolean')
+  }
+
+  if (typeof contextLeakPrevention.blockMetadataExposure !== 'boolean') {
+    throw new TypeError('PolicyRule contextLeakPrevention.blockMetadataExposure must be a boolean')
+  }
+
+  if (typeof contextLeakPrevention.sanitizeInternalReferences !== 'boolean') {
+    throw new TypeError('PolicyRule contextLeakPrevention.sanitizeInternalReferences must be a boolean')
+  }
+
+  const result: PolicyRule = {
+    version: version.trim(),
+    blockedIntents: Object.freeze(Array.from(blockedIntents)) as readonly BlockedIntent[],
+    sensitiveScope: Object.freeze(Array.from(sensitiveScope)) as readonly SensitiveScope[],
+    roleProtection: {
+      protectedRoles: Object.freeze(Array.from(roleProtection.protectedRoles)) as readonly ProtectedRole[],
+      immutableInstructions: Object.freeze(Array.from(roleProtection.immutableInstructions)) as readonly ImmutableInstruction[]
+    },
+    contextLeakPrevention: Object.freeze({ ...contextLeakPrevention })
+  }
+  
+  return result
+}
+
+/**
+ * Funciones puras para PolicyRule
+ */
+export function isIntentBlocked(policy: PolicyRule, intent: string): boolean {
+  return policy.blockedIntents.includes(intent)
+}
+
+export function isScopeSensitive(policy: PolicyRule, scope: string): boolean {
+  return policy.sensitiveScope.includes(scope)
+}
+
+export function isRoleProtected(policy: PolicyRule, role: string): boolean {
+  return policy.roleProtection.protectedRoles.includes(role)
+}
+
+export function isInstructionImmutable(policy: PolicyRule, instruction: string): boolean {
+  return policy.roleProtection.immutableInstructions.includes(instruction)
+}
+
+export function isContextLeakPreventionEnabled(policy: PolicyRule): boolean {
+  return policy.contextLeakPrevention.enabled
+}
+

package/src/isl/value-objects/index.ts

@@ -0,0 +1,41 @@
+// Tipos
+export type { PiDetection } from './PiDetection'
+export type { PiDetectionResult } from './PiDetectionResult'
+export type { AnomalyScore } from './AnomalyScore'
+export type { Pattern } from './Pattern'
+// Funciones de creación
+export {
+  createPiDetection,
+  getDetectionLength,
+  isHighConfidence,
+  isMediumConfidence,
+  isLowConfidence
+} from './PiDetection'
+
+export {
+  createPiDetectionResult,
+  hasDetections,
+  getDetectionCount,
+  getDetectionsByType,
+  getHighestConfidenceDetection
+} from './PiDetectionResult'
+
+export {
+  createAnomalyScore,
+  isHighRisk,
+  isWarnRisk,
+  isLowRisk
+} from './AnomalyScore'
+
+export {
+  createPattern,
+  matchesPattern,
+  findMatch,
+  MAX_CONTENT_LENGTH,
+  MAX_PATTERN_LENGTH,
+  MAX_MATCHES
+} from './Pattern'
+
+// PolicyRule NO es core - va a ModelGateway/Policy Engine
+// Se mantiene el tipo para compatibilidad pero las funciones de decisión no son core
+

package/src/shared/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared utilities for all layers - funciones puras compartidas
+ * 
+ * @remarks
+ * Solo funciones básicas de manejo de linaje.
+ * Auditoría y análisis avanzado van al SDK.
+ */
+
+// Lineage básico
+export * from './lineage'
+
+// Funciones de auditoría NO son core - van al SDK/tooling
+// El core solo preserva linaje, no lo analiza

package/src/shared/lineage.ts

@@ -0,0 +1,53 @@
+import type { LineageEntry } from '@/csl/value-objects'
+
+/**
+ * Lineage global - funciones puras para manejar linaje entre capas
+ * 
+ * @remarks
+ * El linaje es compartido entre todas las capas (CSL, ISL, CPE, etc.)
+ * Cada capa puede agregar entradas al linaje de un segmento.
+ */
+
+/**
+ * Agrega una entrada de linaje a un array existente - función pura
+ * 
+ * @param lineage - Array de entradas de linaje existentes
+ * @param entry - Nueva entrada a agregar
+ * @returns Nuevo array con la entrada agregada
+ */
+export function addLineageEntry(
+  lineage: readonly LineageEntry[],
+  entry: LineageEntry
+): LineageEntry[] {
+  return [...lineage, entry]
+}
+
+/**
+ * Agrega múltiples entradas de linaje - función pura
+ */
+export function addLineageEntries(
+  lineage: readonly LineageEntry[],
+  entries: readonly LineageEntry[]
+): LineageEntry[] {
+  return [...lineage, ...entries]
+}
+
+/**
+ * Filtra entradas de linaje por step - función pura
+ */
+export function filterLineageByStep(
+  lineage: readonly LineageEntry[],
+  step: string
+): LineageEntry[] {
+  return lineage.filter(entry => entry.step === step)
+}
+
+/**
+ * Obtiene la última entrada de linaje - función pura
+ */
+export function getLastLineageEntry(
+  lineage: readonly LineageEntry[]
+): LineageEntry | undefined {
+  return lineage.length > 0 ? lineage.at(-1) : undefined
+}
+

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+      "target": "ES2022",
+      "module": "ESNext",
+      "moduleResolution": "bundler",
+  
+      "outDir": "dist",
+      "baseUrl": ".",
+      "paths": {
+        "@/*": ["src/*"]
+      },
+  
+      "strict": true,
+  
+      "declaration": true,
+      "emitDeclarationOnly": true,
+      "declarationMap": false,
+  
+      "types": ["node"],
+  
+      "noUncheckedIndexedAccess": true,
+      "exactOptionalPropertyTypes": true,
+  
+      "skipLibCheck": true
+    },
+    "include": ["src/**/*", "test/**/*"]
+}