@ai-pip/csl 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felipe Mv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,349 @@
+# @ai-pip/csl - SDK de Context Segmentation Layer
+
+SDK oficial para la capa de segmentación de contexto (CSL) del protocolo AI-PIP. La CSL es responsable de clasificar, etiquetar y aislar el contenido según origen, confiabilidad y riesgo operacional.
+
+## ⚙️ Requisitos
+
+Este SDK está escrito en **TypeScript puro** y requiere:
+
+- **Node.js >= 22.6.0** (última versión LTS recomendada)
+- TypeScript configurado en tu proyecto (si usas TypeScript)
+- Un entorno que soporte módulos ES (ESM)
+
+> **Nota:** Este paquete se distribuye como código TypeScript fuente, por lo que necesitas una versión moderna de Node.js que soporte las características de ES modules y TypeScript nativo, o un bundler/transpilador configurado en tu proyecto.
+
+## 📦 Instalación
+
+```bash
+npm install @ai-pip/csl
+# o
+pnpm add @ai-pip/csl
+# o
+yarn add @ai-pip/csl
+```
+
+## 🚀 Uso Básico
+
+### Ejemplo Simple
+
+```typescript
+import { createCSLService } from '@ai-pip/csl'
+
+// Crear servicio con configuración por defecto
+const cslService = createCSLService()
+
+// Procesar contenido del DOM
+const result = await cslService.segment(document.body)
+
+// Acceder a los resultados
+console.log(`Segmentos procesados: ${result.metadata.total_segments}`)
+console.log(`Segmentos bloqueados: ${result.getBlockedCount()}`)
+
+// Iterar sobre segmentos
+result.segments.forEach(segment => {
+  console.log(`Segmento ${segment.id}:`)
+  console.log(`  - Nivel de confianza: ${segment.trustLevel?.value}`)
+  console.log(`  - Contenido: ${segment.content}`)
+  console.log(`  - Score de anomalía: ${segment.anomalyScore?.score}`)
+  
+  if (segment.shouldBlock()) {
+    console.log(`  ⚠️  Este segmento debe ser bloqueado`)
+  }
+})
+```
+
+## ⚙️ Configuración Avanzada
+
+### Con Opciones Personalizadas
+
+```typescript
+import { createCSLService } from '@ai-pip/csl'
+
+const cslService = createCSLService({
+  // Habilitar validación de políticas
+  enablePolicyValidation: true,
+  
+  // Habilitar tracking de linaje
+  enableLineageTracking: true,
+  
+  // Usar algoritmo SHA-512 para hashes
+  hashAlgorithm: 'sha512'
+})
+
+const result = await cslService.segment(document.body)
+```
+
+### Con Dependencias Personalizadas
+
+```typescript
+import { 
+  createCSLService,
+  ConsoleLogger,
+  InMemoryPolicyRepository,
+  PolicyRule,
+  SystemTimestamProvider
+} from '@ai-pip/csl'
+
+// Crear logger personalizado
+class CustomLogger extends ConsoleLogger {
+  error(message: string) {
+    // Enviar a servicio de logging externo
+    super.error(message)
+  }
+}
+
+// Configurar políticas
+const policyRepository = new InMemoryPolicyRepository()
+const policy = new PolicyRule({
+  version: '1.0',
+  blockedIntents: ['delete_user_data', 'modify_system_settings'],
+  sensitiveScope: ['financial_transactions'],
+  // ... más configuración
+})
+await policyRepository.savePolicy(policy)
+
+// Crear servicio con dependencias personalizadas
+const cslService = createCSLService({
+  logger: new CustomLogger(),
+  policyRepository: policyRepository,
+  enablePolicyValidation: true
+})
+
+const result = await cslService.segment(document.body)
+```
+
+## 📚 API Reference
+
+### `createCSLService(options?)`
+
+Función factory que crea una instancia de `CSLService` con todas sus dependencias configuradas.
+
+**Parámetros:**
+- `options` (opcional): Objeto de configuración
+  - `enablePolicyValidation?: boolean` - Habilita validación de políticas (default: `true`)
+  - `enableLineageTracking?: boolean` - Habilita tracking de linaje (default: `true`)
+  - `hashAlgorithm?: 'sha256' | 'sha512'` - Algoritmo de hash (default: `'sha256'`)
+  - `policyRepository?: PolicyRepositoryPort` - Repositorio de políticas personalizado
+  - `logger?: LoggerPort` - Logger personalizado
+  - `hashGenerator?: HashGeneratorPort` - Generador de hash personalizado
+  - `timestampProvider?: TimeStampProviderPort` - Proveedor de timestamps personalizado
+
+**Retorna:** `CSLService`
+
+### `CSLService.segment(element)`
+
+Procesa un elemento DOM o documento a través del pipeline completo de CSL.
+
+**Parámetros:**
+- `element: HTMLElement | Document` - El elemento DOM o documento a procesar
+
+**Retorna:** `Promise<CSLResult>`
+
+**Lanza:** `SegmentationError` si el procesamiento falla
+
+### `CSLResult`
+
+Resultado del procesamiento de segmentación.
+
+**Propiedades:**
+- `segments: Segment[]` - Array de segmentos procesados
+- `metadata: CSLResultMetadata` - Metadatos del procesamiento
+- `lineage: LineageEntry[]` - Entradas de linaje para trazabilidad
+
+**Métodos:**
+- `getBlockedCount(): number` - Retorna el número de segmentos bloqueados
+- `getTrustDistribution(): { TC: number, STC: number, UC: number }` - Distribución de niveles de confianza
+
+### `Segment`
+
+Representa un segmento de contenido procesado.
+
+**Propiedades:**
+- `id: string` - Identificador único
+- `content: string` - Contenido del segmento
+- `origin: Origin` - Origen del contenido
+- `trustLevel?: TrustLevel` - Nivel de confianza (TC, STC, UC)
+- `anomalyScore?: AnomalyScore` - Score de anomalía
+- `piDetection?: PiDetection` - Detección de prompt injection
+- `hash?: ContentHash` - Hash del contenido
+- `lineage?: LineageEntry[]` - Entradas de linaje
+
+**Métodos:**
+- `shouldBlock(): boolean` - Indica si el segmento debe ser bloqueado
+
+## 🔍 Ejemplos de Uso
+
+### Procesar un Formulario
+
+```typescript
+import { createCSLService } from '@ai-pip/csl'
+
+const cslService = createCSLService()
+
+// Procesar un formulario específico
+const form = document.getElementById('user-form')
+const result = await cslService.segment(form)
+
+// Filtrar solo segmentos confiables
+const trustedSegments = result.segments.filter(
+  segment => segment.trustLevel?.value === 'TC'
+)
+
+console.log(`Segmentos confiables: ${trustedSegments.length}`)
+```
+
+### Detectar Prompt Injection
+
+```typescript
+import { createCSLService } from '@ai-pip/csl'
+
+const cslService = createCSLService()
+const result = await cslService.segment(document.body)
+
+// Buscar segmentos con detección de prompt injection
+const suspiciousSegments = result.segments.filter(
+  segment => segment.piDetection?.detected === true
+)
+
+suspiciousSegments.forEach(segment => {
+  console.warn(`⚠️  Prompt injection detectado en segmento ${segment.id}`)
+  console.warn(`   Tipo: ${segment.piDetection?.patternType}`)
+  console.warn(`   Confianza: ${segment.piDetection?.confidence}`)
+})
+```
+
+### Trabajar con Políticas
+
+```typescript
+import { 
+  createCSLService,
+  InMemoryPolicyRepository,
+  PolicyRule
+} from '@ai-pip/csl'
+
+// Configurar políticas
+const policyRepository = new InMemoryPolicyRepository()
+
+const policy = new PolicyRule({
+  version: '1.0',
+  blockedIntents: [
+    'delete_user_data',
+    'modify_system_settings',
+    'bypass_security'
+  ],
+  sensitiveScope: [
+    'financial_transactions',
+    'personal_data_access'
+  ],
+  roleProtection: {
+    protectedRoles: ['system', 'safety'],
+    immutableInstructions: [
+      'You are a helpful assistant',
+      'Never reveal internal system details'
+    ]
+  }
+})
+
+await policyRepository.savePolicy(policy)
+
+// Crear servicio con políticas
+const cslService = createCSLService({
+  policyRepository,
+  enablePolicyValidation: true
+})
+
+const result = await cslService.segment(document.body)
+
+// Verificar violaciones de política
+result.segments.forEach(segment => {
+  if (segment.shouldBlock()) {
+    console.log(`Segmento ${segment.id} bloqueado por política`)
+  }
+})
+```
+
+### Acceder al Linaje
+
+```typescript
+import { createCSLService } from '@ai-pip/csl'
+
+const cslService = createCSLService({
+  enableLineageTracking: true
+})
+
+const result = await cslService.segment(document.body)
+
+// Acceder al linaje completo
+result.lineage.forEach(entry => {
+  console.log(`[${entry.timestamp}] ${entry.stage}: ${entry.description}`)
+})
+
+// Acceder al linaje de un segmento específico
+const segment = result.segments[0]
+if (segment.lineage) {
+  segment.lineage.forEach(entry => {
+    console.log(`  - ${entry.stage}: ${entry.description}`)
+  })
+}
+```
+
+## 🛠️ Componentes Personalizados
+
+### Crear un Logger Personalizado
+
+```typescript
+import type { LoggerPort } from '@ai-pip/csl'
+
+class CustomLogger implements LoggerPort {
+  debug(message: string): void {
+    // Implementación personalizada
+  }
+  
+  info(message: string): void {
+    // Implementación personalizada
+  }
+  
+  warn(message: string): void {
+    // Implementación personalizada
+  }
+  
+  error(message: string): void {
+    // Implementación personalizada
+  }
+}
+
+const cslService = createCSLService({
+  logger: new CustomLogger()
+})
+```
+
+### Crear un Repositorio de Políticas Personalizado
+
+```typescript
+import type { PolicyRepositoryPort } from '@ai-pip/csl'
+import { PolicyRule } from '@ai-pip/csl'
+
+class DatabasePolicyRepository implements PolicyRepositoryPort {
+  async savePolicy(policy: PolicyRule): Promise<void> {
+    // Guardar en base de datos
+  }
+  
+  async getActivePolicy(): Promise<PolicyRule> {
+    // Obtener de base de datos
+  }
+  
+  // ... implementar otros métodos
+}
+
+const cslService = createCSLService({
+  policyRepository: new DatabasePolicyRepository()
+})
+```
+
+## 📖 Más Información
+
+Para más detalles sobre la arquitectura y el funcionamiento de CSL, consulta la [documentación completa](../../docs/layer/csl.md).
+
+## 📄 Licencia
+
+MIT

package/index.ts

@@ -0,0 +1,273 @@
+/**
+ * @ai-pip/csl - SDK para la capa de segmentación de contexto (CSL)
+ * 
+ * Este SDK proporciona una interfaz completa para usar la CSL (Context Segmentation Layer)
+ * del protocolo AI-PIP. La CSL es responsable de clasificar, etiquetar y aislar el contenido
+ * según origen, confiabilidad y riesgo operacional.
+ * 
+ * @example
+ * ```typescript
+ * import { createCSLService } from '@ai-pip/csl'
+ * 
+ * // Crear servicio con configuración por defecto
+ * const cslService = createCSLService()
+ * 
+ * // Procesar contenido del DOM
+ * const result = await cslService.segment(document.body)
+ * 
+ * // Acceder a los resultados
+ * console.log(`Segmentos procesados: ${result.metadata.total_segments}`)
+ * console.log(`Segmentos bloqueados: ${result.getBlockedCount()}`)
+ * ```
+ * 
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// EXPORTACIONES PRINCIPALES
+// ============================================================================
+
+// Servicio principal
+export { CSLService, type CSLServiceConfig } from './layers/csl/services/CSLService'
+
+// ============================================================================
+// PORTS (Interfaces públicas)
+// ============================================================================
+
+// Input ports (interfaces que CSL expone)
+export type { SegmentationPort } from './layers/csl/ports/input/SegmentationPort'
+export type { ClassificationPort } from './layers/csl/ports/input/ClassificationPort'
+
+// Output ports (interfaces que CSL necesita)
+export type { LoggerPort } from './layers/csl/ports/output/Logger'
+export type { HashGeneratorPort } from './layers/csl/ports/output/HashGenerator'
+export type { TimeStampProviderPort } from './layers/csl/ports/output/TimeStampProvider'
+export type { PolicyRepositoryPort } from './layers/csl/ports/output/PolicyRepository'
+export type { SegmentClassified } from './layers/csl/ports/output/SegmentClassified'
+
+// ============================================================================
+// ENTIDADES
+// ============================================================================
+
+export { CSLResult } from './layers/csl/domain/entities/CSLResult'
+export { Segment } from './layers/csl/domain/entities/Segment'
+
+// ============================================================================
+// VALUE OBJECTS
+// ============================================================================
+
+export { Origin } from './layers/csl/domain/value-objects/Origin'
+export { TrustLevel } from './layers/csl/domain/value-objects/TrustLevel'
+export { AnomalyScore } from './layers/csl/domain/value-objects/AnomalyScore'
+export { ContentHash } from './layers/csl/domain/value-objects/ContentHash'
+export { LineageEntry } from './layers/csl/domain/value-objects/LineageEntry'
+export { PiDetection } from './layers/csl/domain/value-objects/PiDetection'
+export { PiDetectionResult } from './layers/csl/domain/value-objects/PiDetectionResult'
+export { PolicyRule } from './layers/csl/domain/value-objects/PolicyRule'
+export { Pattern } from './layers/csl/domain/value-objects/Pattern'
+
+// ============================================================================
+// SERVICIOS DE DOMINIO
+// ============================================================================
+
+export { NormalizationService } from './layers/csl/domain/services/NormalizationService'
+export { OriginClassificationService } from './layers/csl/domain/services/OriginClassificationService'
+export { PiDetectionService } from './layers/csl/domain/services/PiDetectionService'
+export { AnomalyService } from './layers/csl/domain/services/AnomalyService'
+export { PolicyService } from './layers/csl/domain/services/PolicyService'
+export { LineageService } from './layers/csl/domain/services/LineageService'
+export { SerializationService } from './layers/csl/domain/services/SerializationService'
+
+// ============================================================================
+// ADAPTERS (Implementaciones por defecto)
+// ============================================================================
+
+// Input adapters
+export { DOMAdapter } from './layers/csl/adapters/input/DOMAdapter'
+
+// Output adapters
+export { ConsoleLogger } from './layers/csl/adapters/output/ConsoleLogger'
+export { CryptoHashGenerator } from './layers/csl/adapters/output/CryptoHashGenerator'
+export { SystemTimestamProvider } from './layers/csl/adapters/output/SystemTimestampProvider'
+export { InMemoryPolicyRepository } from './layers/csl/adapters/output/InMemoryPolicyRepository'
+
+// ============================================================================
+// EXCEPCIONES
+// ============================================================================
+
+export { SegmentationError } from './layers/csl/domain/exceptions/SegmentationError'
+export { ClassificationError } from './layers/csl/domain/exceptions/ClassificationError'
+
+// ============================================================================
+// TIPOS
+// ============================================================================
+
+export type * from './layers/csl/types'
+
+// ============================================================================
+// FACTORY FUNCTION - Creación fácil del servicio
+// ============================================================================
+
+import { CSLService, type CSLServiceConfig } from './layers/csl/services/CSLService'
+import { DOMAdapter } from './layers/csl/adapters/input/DOMAdapter'
+import { OriginClassificationService } from './layers/csl/domain/services/OriginClassificationService'
+import { PiDetectionService } from './layers/csl/domain/services/PiDetectionService'
+import { AnomalyService } from './layers/csl/domain/services/AnomalyService'
+import { PolicyService } from './layers/csl/domain/services/PolicyService'
+import { LineageService } from './layers/csl/domain/services/LineageService'
+import { CryptoHashGenerator } from './layers/csl/adapters/output/CryptoHashGenerator'
+import { ConsoleLogger } from './layers/csl/adapters/output/ConsoleLogger'
+import { SystemTimestamProvider } from './layers/csl/adapters/output/SystemTimestampProvider'
+import { InMemoryPolicyRepository } from './layers/csl/adapters/output/InMemoryPolicyRepository'
+import type { PolicyRepositoryPort } from './layers/csl/ports/output/PolicyRepository'
+import type { LoggerPort } from './layers/csl/ports/output/Logger'
+import type { HashGeneratorPort } from './layers/csl/ports/output/HashGenerator'
+import type { TimeStampProviderPort } from './layers/csl/ports/output/TimeStampProvider'
+
+/**
+ * Opciones para crear el servicio CSL
+ * @props 
+ *  - enablePolicyValidation?: boolean
+ *  - enableLineageTracking?: boolean
+ *  - hashAlgorithm?: 'sha256' | 'sha512'
+ *  - policyRepository?: PolicyRepositoryPort
+ *  - logger?: LoggerPort
+ *  - hashGenerator?: HashGeneratorPort
+ *  - timestampProvider?: TimeStampProviderPort
+ * @example
+ * ```typescript
+ * const options: CreateCSLServiceOptions = {
+ *   enablePolicyValidation: true,
+ *   enableLineageTracking: true,
+ *   hashAlgorithm: 'sha512'
+ * }
+
+ */
+export interface CreateCSLServiceOptions extends Partial<CSLServiceConfig> {
+  /**
+   * Repositorio de políticas personalizado.
+   * Si no se proporciona, se usa InMemoryPolicyRepository por defecto.
+   */
+  policyRepository?: PolicyRepositoryPort
+
+  /**
+   * Logger personalizado.
+   * Si no se proporciona, se usa ConsoleLogger por defecto.
+   */
+  logger?: LoggerPort
+
+  /**
+   * Generador de hash personalizado.
+   * Si no se proporciona, se usa CryptoHashGenerator por defecto.
+   */
+  hashGenerator?: HashGeneratorPort
+
+  /**
+   * Proveedor de timestamps personalizado.
+   * Si no se proporciona, se usa SystemTimestampProvider por defecto.
+   */
+  timestampProvider?: TimeStampProviderPort
+}
+
+/**
+ * Crea una instancia de CSLService con todas sus dependencias configuradas.
+ * 
+ * Esta función factory simplifica la creación del servicio CSL proporcionando
+ * implementaciones por defecto para todas las dependencias. Los usuarios pueden
+ * personalizar cualquier componente pasando opciones personalizadas.
+ * 
+ * @param options - Opciones de configuración para el servicio y sus dependencias
+ * 
+ * @returns Una instancia configurada de CSLService lista para usar
+ * 
+ * @example
+ * ```typescript
+ * // Uso básico con configuración por defecto
+ * const cslService = createCSLService()
+ * 
+ * // Con configuración personalizada
+ * const cslService = createCSLService({
+ *   enablePolicyValidation: true,
+ *   enableLineageTracking: true,
+ *   hashAlgorithm: 'sha512'
+ * })
+ * 
+ * // Con dependencias personalizadas
+ * const customLogger = new CustomLogger()
+ * const customPolicyRepo = new CustomPolicyRepository()
+ * 
+ * const cslService = createCSLService({
+ *   logger: customLogger,
+ *   policyRepository: customPolicyRepo,
+ *   enablePolicyValidation: true
+ * })
+ * 
+ * // Procesar contenido
+ * const result = await cslService.segment(document.body)
+ * ```
+ */
+export function createCSLService(options?: CreateCSLServiceOptions): CSLService {
+  // Crear adapters con implementaciones por defecto o personalizadas
+  const domAdapter = new DOMAdapter()
+  
+  const logger: LoggerPort = options?.logger ?? new ConsoleLogger()
+  const hashGenerator: HashGeneratorPort = options?.hashGenerator ?? new CryptoHashGenerator()
+  const timestampProvider: TimeStampProviderPort = options?.timestampProvider ?? new SystemTimestamProvider()
+  const policyRepository: PolicyRepositoryPort = options?.policyRepository ?? new InMemoryPolicyRepository()
+
+  // Crear servicios de dominio
+  const originClassificationService = new OriginClassificationService()
+  const piDetectionService = new PiDetectionService()
+  const anomalyService = new AnomalyService()
+  const policyService = new PolicyService(policyRepository)
+  const lineageService = new LineageService()
+
+  // Crear configuración del servicio
+  const config: CSLServiceConfig | undefined = (() => {
+    const hasAnyConfig = 
+      options?.enablePolicyValidation !== undefined ||
+      options?.enableLineageTracking !== undefined ||
+      options?.hashAlgorithm !== undefined
+    
+    if (!hasAnyConfig) {
+      return undefined
+    }
+    
+    // Construir objeto literal inmutable
+    const configObj: CSLServiceConfig = {
+      ...(options?.enablePolicyValidation !== undefined && { 
+        enablePolicyValidation: options.enablePolicyValidation 
+      }),
+      ...(options?.enableLineageTracking !== undefined && { 
+        enableLineageTracking: options.enableLineageTracking 
+      }),
+      ...(options?.hashAlgorithm !== undefined && { 
+        hashAlgorithm: options.hashAlgorithm 
+      }),
+    }
+    return configObj
+  })()
+
+  // Crear y retornar el servicio
+  return new CSLService(
+    domAdapter,
+    originClassificationService,
+    piDetectionService,
+    anomalyService,
+    policyService,
+    lineageService,
+    hashGenerator,
+    logger,
+    timestampProvider,
+    config
+  )
+}
+
+// ============================================================================
+// EXPORTACIÓN POR DEFECTO
+// ============================================================================
+
+/**
+ * Exportación por defecto: función factory para crear el servicio
+ */
+export default createCSLService

package/layers/csl/adapters/index.ts

@@ -0,0 +1,9 @@
+// input
+export * from './input/DOMAdapter';
+
+
+
+// output
+export * from './output/ConsoleLogger'
+export * from './output/SystemTimestampProvider'
+export * from './output/CryptoHashGenerator'