@ai-pip/core 0.1.0

package/src/cpe/utils.ts

@@ -0,0 +1,65 @@
+/**
+ * Utilidades puras para CPE
+ */
+
+/**
+ * Serializa el contenido sanitizado de ISL para firma
+ * 
+ * @param segments - Segmentos sanitizados
+ * @returns Contenido serializado
+ */
+export function serializeContent(segments: readonly { readonly sanitizedContent: string }[]): string {
+  return segments
+    .map((segment, index) => `[${index}]:${segment.sanitizedContent}`)
+    .join('\n')
+}
+
+/**
+ * Serializa metadata para firma
+ * 
+ * @param metadata - Metadata a serializar
+ * @returns Metadata serializada
+ */
+export function serializeMetadata(metadata: {
+  readonly timestamp: number
+  readonly nonce: string
+  readonly protocolVersion: string
+  readonly previousSignatures?: {
+    readonly csl?: string | undefined
+    readonly isl?: string | undefined
+  } | undefined
+}): string {
+  const parts = [
+    `timestamp:${metadata.timestamp}`,
+    `nonce:${metadata.nonce}`,
+    `version:${metadata.protocolVersion}`,
+  ]
+
+  if (metadata.previousSignatures?.csl) {
+    parts.push(`csl:${metadata.previousSignatures.csl}`)
+  }
+
+  if (metadata.previousSignatures?.isl) {
+    parts.push(`isl:${metadata.previousSignatures.isl}`)
+  }
+
+  return parts.join('|')
+}
+
+/**
+ * Genera el contenido completo para firma
+ * Según spec: contenido procesado + metadata + identificador del algoritmo
+ * 
+ * @param content - Contenido serializado (payload semántico)
+ * @param metadata - Metadata serializada
+ * @param algorithm - Identificador del algoritmo de firma
+ * @returns Contenido completo para firma
+ */
+export function generateSignableContent(
+  content: string,
+  metadata: string,
+  algorithm: string
+): string {
+  return `${metadata}\n---\n${content}\n---\nalgorithm:${algorithm}`
+}
+

package/src/cpe/value-objects/Metadata.ts

@@ -0,0 +1,78 @@
+/**
+ * CPEMetadata - Metadata de seguridad del envelope
+ * Value Object puro e inmutable
+ */
+
+import type { CPEMetadata, ProtocolVersion, Timestamp } from '../types'
+import type { Nonce as NonceVO } from './Nonce'
+
+/**
+ * Versión actual del protocolo
+ */
+export const CURRENT_PROTOCOL_VERSION: ProtocolVersion = '1.0.0'
+
+/**
+ * Crea metadata de seguridad para el envelope
+ * Según especificación: timestamp, nonce, protocolVersion, previousSignatures opcionales
+ * 
+ * @param timestamp - Timestamp Unix en milisegundos
+ * @param nonce - Nonce único
+ * @param protocolVersion - Versión del protocolo (default: CURRENT_PROTOCOL_VERSION)
+ * @param previousSignatures - Firmas opcionales de capas anteriores (csl, isl)
+ * @returns CPEMetadata inmutable
+ */
+export function createMetadata(
+  timestamp: Timestamp,
+  nonce: NonceVO,
+  protocolVersion: ProtocolVersion = CURRENT_PROTOCOL_VERSION,
+  previousSignatures?: {
+    csl?: string
+    isl?: string
+  }
+): CPEMetadata {
+  // Validar timestamp
+  if (timestamp <= 0) {
+    throw new Error('Timestamp must be a positive number')
+  }
+
+  // Validar que no sea del futuro (con margen de 5 minutos para sincronización)
+  const maxFutureTimestamp = Date.now() + 5 * 60 * 1000
+  if (timestamp > maxFutureTimestamp) {
+    throw new Error('Timestamp cannot be in the future')
+  }
+
+  // Validar version del protocolo
+  if (!protocolVersion || typeof protocolVersion !== 'string') {
+    throw new Error('Protocol version must be a non-empty string')
+  }
+
+  return Object.freeze({
+    timestamp,
+    nonce: nonce.value,
+    protocolVersion,
+    previousSignatures: previousSignatures
+      ? Object.freeze({
+          csl: previousSignatures.csl ?? undefined,
+          isl: previousSignatures.isl ?? undefined,
+        })
+      : undefined,
+  })
+}
+
+/**
+ * Valida que la metadata sea válida
+ * 
+ * @param metadata - Metadata a validar
+ * @returns true si es válida
+ */
+export function isValidMetadata(metadata: CPEMetadata): boolean {
+  try {
+    if (metadata.timestamp <= 0) return false
+    if (!metadata.nonce || metadata.nonce.length < 16) return false
+    if (!metadata.protocolVersion) return false
+    return true
+  } catch {
+    return false
+  }
+}
+

package/src/cpe/value-objects/Nonce.ts

@@ -0,0 +1,57 @@
+/**
+ * Nonce - Valor único para prevenir ataques de replay
+ * Value Object puro e inmutable
+ */
+
+import { randomBytes } from 'node:crypto'
+
+/**
+ * Nonce - Valor único generado aleatoriamente
+ */
+export type Nonce = {
+  readonly value: string
+}
+
+/**
+ * Genera un nonce único
+ * 
+ * @param length - Longitud del nonce en bytes (default: 16)
+ * @returns Nonce único
+ */
+export function createNonce(length: number = 16): Nonce {
+  if (length < 8) {
+    throw new Error('Nonce length must be at least 8 bytes')
+  }
+  if (length > 64) {
+    throw new Error('Nonce length must be at most 64 bytes')
+  }
+
+  const bytes = randomBytes(length)
+  const value = bytes.toString('hex')
+
+  return Object.freeze({
+    value,
+  })
+}
+
+/**
+ * Valida que un string sea un nonce válido
+ * 
+ * @param value - String a validar
+ * @returns true si es un nonce válido
+ */
+export function isValidNonce(value: string): boolean {
+  return /^[a-f0-9]{16,128}$/i.test(value)
+}
+
+/**
+ * Compara dos nonces
+ * 
+ * @param nonce1 - Primer nonce
+ * @param nonce2 - Segundo nonce
+ * @returns true si son iguales
+ */
+export function equalsNonce(nonce1: Nonce, nonce2: Nonce): boolean {
+  return nonce1.value === nonce2.value
+}
+

package/src/cpe/value-objects/Signature.ts

@@ -0,0 +1,83 @@
+/**
+ * Signature - Firma criptográfica HMAC-SHA256
+ * Value Object puro e inmutable
+ */
+
+import { createHmac } from 'node:crypto'
+import type { SignatureAlgorithm } from '../types'
+
+/**
+ * Signature - Firma criptográfica
+ */
+export type SignatureVO = {
+  readonly value: string
+  readonly algorithm: SignatureAlgorithm
+}
+
+/**
+ * Genera una firma HMAC-SHA256 del contenido
+ * 
+ * @param content - Contenido a firmar
+ * @param secretKey - Clave secreta para HMAC
+ * @returns Signature inmutable
+ * 
+ * @throws {Error} Si la clave secreta está vacía
+ */
+export function createSignature(
+  content: string,
+  secretKey: string
+): SignatureVO {
+  if (!secretKey || secretKey.length === 0) {
+    throw new Error('Secret key is required for signature generation')
+  }
+
+  if (typeof content !== 'string') {
+    throw new TypeError('Content must be a string')
+  }
+
+  const hmac = createHmac('sha256', secretKey)
+  hmac.update(content)
+  const signature = hmac.digest('hex')
+
+  return Object.freeze({
+    value: signature,
+    algorithm: 'HMAC-SHA256',
+  })
+}
+
+/**
+ * Verifica una firma HMAC-SHA256
+ * 
+ * @param content - Contenido original
+ * @param signature - Firma a verificar
+ * @param secretKey - Clave secreta para HMAC
+ * @returns true si la firma es válida
+ */
+export function verifySignature(
+  content: string,
+  signature: string,
+  secretKey: string
+): boolean {
+  if (!secretKey || secretKey.length === 0) {
+    return false
+  }
+
+  try {
+    const expectedSignature = createSignature(content, secretKey)
+    return expectedSignature.value === signature
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Valida el formato de una firma
+ * 
+ * @param signature - Firma a validar
+ * @returns true si el formato es válido
+ */
+export function isValidSignatureFormat(signature: string): boolean {
+  // HMAC-SHA256 produce un hash hexadecimal de 64 caracteres
+  return /^[a-f0-9]{64}$/i.test(signature)
+}
+

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

@@ -0,0 +1,8 @@
+/**
+ * CPE Value Objects - Exports
+ */
+
+export * from './Nonce'
+export * from './Metadata'
+export * from './Signature'
+

package/src/csl/classify.ts

@@ -0,0 +1,77 @@
+import { createTrustLevel } from './value-objects/TrustLevel'
+import type { Origin } from './value-objects/Origin'
+import { originMap } from './value-objects/Origin-map'
+import { ClassificationError } from './exceptions'
+import { OriginType } from './types'
+import type { Source } from './types'
+
+/**
+ * Clasifica un source y retorna su TrustLevel - función pura determinista
+ * 
+ * @remarks
+ * - 100% determinista: mismo source → mismo trust level, siempre
+ * - Sin efectos secundarios: función pura
+ * - Sin análisis de contenido: solo el source importa
+ * 
+ * @param source - El source del contenido ('DOM' | 'UI' | 'SYSTEM' | 'API')
+ * @returns TrustLevel determinado por el source
+ * 
+ * @throws {ClassificationError} Si el source no puede ser clasificado
+ * 
+ * @example
+ * ```typescript
+ * const trust = classifySource('UI')
+ * // Returns: { value: 'TC' }
+ * 
+ * const trust2 = classifySource('DOM')
+ * // Returns: { value: 'STC' }
+ * ```
+ */
+export function classifySource(source: Source) {
+  // Mapeo simple: Source → OriginType → TrustLevel
+  const sourceToOriginType: Record<Source, OriginType> = {
+    'UI': OriginType.SYSTEM_GENERATED,      // UI directa → TC
+    'SYSTEM': OriginType.SYSTEM_GENERATED,   // System → TC
+    'DOM': OriginType.DOM_VISIBLE,           // DOM → STC
+    'API': OriginType.NETWORK_FETCHED        // API → UC
+  }
+  
+  const originType = sourceToOriginType[source]
+  
+  if (!originType) {
+    throw new ClassificationError(`Source '${source}' cannot be classified`)
+  }
+  
+  const trustLevelType = originMap.get(originType)
+  
+  if (!trustLevelType) {
+    throw new ClassificationError(
+      `Origin type '${originType}' is not mapped in originMap. ` +
+      `All OriginType values must have a corresponding TrustLevel mapping.`
+    )
+  }
+  
+  return createTrustLevel(trustLevelType)
+}
+
+/**
+ * Clasifica un Origin y retorna su TrustLevel - función pura determinista
+ * 
+ * @param origin - El Origin value object
+ * @returns TrustLevel determinado por el origin
+ * 
+ * @throws {ClassificationError} Si el origin no está mapeado
+ */
+export function classifyOrigin(origin: Origin) {
+  const trustLevelType = originMap.get(origin.type)
+  
+  if (!trustLevelType) {
+    throw new ClassificationError(
+      `Origin type '${origin.type}' is not mapped in originMap. ` +
+      `All OriginType values must have a corresponding TrustLevel mapping.`
+    )
+  }
+  
+  return createTrustLevel(trustLevelType)
+}
+

package/src/csl/exceptions/ClassificationError.ts

@@ -0,0 +1,16 @@
+/**
+ * ClassificationError is thrown when classification fails.
+ * 
+ * @remarks
+ * This error is thrown when:
+ * - An origin type is not mapped in originMap
+ * - Classification cannot be determined
+ */
+export class ClassificationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ClassificationError'
+    Object.setPrototypeOf(this, ClassificationError.prototype)
+  }
+}
+

package/src/csl/exceptions/SegmentationError.ts

@@ -0,0 +1,19 @@
+/**
+ * SegmentationError is thrown when the segmentation process fails.
+ * 
+ * @remarks
+ * This error is thrown when:
+ * - Content segmentation fails
+ * - Critical pipeline steps fail
+ */
+export class SegmentationError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: unknown
+  ) {
+    super(message)
+    this.name = 'SegmentationError'
+    Object.setPrototypeOf(this, SegmentationError.prototype)
+  }
+}
+

package/src/csl/exceptions/index.ts

@@ -0,0 +1,3 @@
+export * from './ClassificationError'
+export * from './SegmentationError'
+

package/src/csl/index.ts

@@ -0,0 +1,34 @@
+/**
+ * CSL (Context Segmentation Layer) - Core Semántico
+ * 
+ * @remarks
+ * Este es el core semántico de CSL. Solo contiene:
+ * - Funciones puras (sin estado)
+ * - Value objects inmutables
+ * - Tipos y excepciones
+ * 
+ * **NO contiene:**
+ * - Detección de prompt injection (va a ISL)
+ * - Políticas (van a ISL)
+ * - Anomaly scores (van a ISL)
+ * - Normalización agresiva (va a ISL)
+ * - Servicios con estado (van al SDK)
+ */
+
+// Funciones puras principales
+export { segment } from './segment'
+export { classifySource, classifyOrigin } from './classify'
+export { initLineage, createLineageEntry } from './lineage'
+
+// Value objects
+export * from './value-objects'
+
+// Exceptions
+export * from './exceptions'
+
+// Types
+export * from './types'
+
+// Utils
+export { generateId, splitByContextRules } from './utils'
+

package/src/csl/lineage.ts

@@ -0,0 +1,40 @@
+import { createLineageEntry as createEntry } from './value-objects/LineageEntry'
+import type { LineageEntry } from './value-objects/LineageEntry'
+import type { CSLSegment } from './types'
+
+/**
+ * Inicializa el linaje para un segmento - función pura
+ * 
+ * @remarks
+ * Crea la entrada inicial de linaje cuando se crea un segmento en CSL.
+ * El core solo registra step y timestamp, sin notes.
+ * 
+ * @param segment - El segmento para el cual inicializar el linaje
+ * @returns Array con la entrada inicial de linaje
+ * 
+ * @example
+ * ```typescript
+ * const lineage = initLineage(segment)
+ * // Returns: [{ step: 'CSL', timestamp: ... }]
+ * ```
+ */
+export function initLineage(_segment: CSLSegment): LineageEntry[] {
+  return [
+    createEntry('CSL', Date.now())
+  ]
+}
+
+/**
+ * Crea una entrada de linaje - función pura
+ * 
+ * @remarks
+ * El core solo registra step y timestamp.
+ * Notes y metadata van en el SDK para observabilidad.
+ * 
+ * @param step - Nombre del paso de procesamiento
+ * @returns Nueva entrada de linaje
+ */
+export function createLineageEntry(step: string): LineageEntry {
+  return createEntry(step, Date.now())
+}
+

package/src/csl/segment.ts

@@ -0,0 +1,100 @@
+import type { CSLInput, CSLResult, CSLSegment } from './types'
+import { classifySource } from './classify'
+import { initLineage } from './lineage'
+import { generateId, splitByContextRules } from './utils'
+import { SegmentationError } from './exceptions'
+
+/**
+ * Segmenta input en segmentos semánticos - función pura principal de CSL
+ * 
+ * @remarks
+ * Esta es la función principal de CSL. Segmenta el contenido, clasifica
+ * por origen, e inicializa el linaje. Todo de forma pura y determinista.
+ * 
+ * **Invariantes preservados:**
+ * - El contenido original nunca se pierde
+ * - El orden de segmentos es estable
+ * - Todo segmento tiene linaje inicial
+ * - CSL es determinista
+ * 
+ * @param input - Input con contenido y source
+ * @returns CSLResult con segmentos clasificados y linaje inicializado
+ * 
+ * @throws {SegmentationError} Si la segmentación falla
+ * 
+ * @example
+ * ```typescript
+ * const result = segment({
+ *   content: 'Hello\nWorld',
+ *   source: 'UI',
+ *   metadata: {}
+ * })
+ * 
+ * // result.segments contiene 2 segmentos, cada uno con:
+ * // - content original
+ * // - trust level clasificado
+ * // - lineage inicializado
+ * ```
+ */
+export function segment(input: CSLInput): CSLResult {
+  try {
+    // 1. Validar input
+    if (!input.content || typeof input.content !== 'string') {
+      throw new SegmentationError('CSLInput content must be a non-empty string')
+    }
+
+    if (!input.source) {
+      throw new SegmentationError('CSLInput source is required')
+    }
+
+    // 2. Dividir contenido en segmentos estructurales (función pura)
+    // CSL solo segmenta por estructura, no por intención semántica
+    const contentSegments = splitByContextRules(input.content)
+
+    // 3. Si no hay contenido, retornar resultado vacío
+    if (contentSegments.length === 0) {
+      return {
+        segments: Object.freeze([]),
+        lineage: Object.freeze([])
+      }
+    }
+
+    // 4. Clasificar source una vez (determinista)
+    const trust = classifySource(input.source)
+
+    // 5. Crear segmentos con clasificación y linaje
+    const segments: CSLSegment[] = contentSegments.map((content) => {
+      // Crear segmento temporal para inicializar linaje
+      const tempSegment: CSLSegment = {
+        id: generateId(),
+        content,                    // ✅ Original preservado
+        source: input.source,       // ✅ Origen preservado
+        trust,                      // ✅ Clasificación determinista
+        lineage: [],                // Se inicializa después
+        ...(input.metadata && { metadata: input.metadata })
+      }
+      
+      // Inicializar linaje
+      const lineage = initLineage(tempSegment)
+      
+      // Retornar segmento completo
+      return {
+        ...tempSegment,
+        lineage                      // ✅ Linaje inicializado
+      }
+    })
+
+    // 6. Recolectar todo el linaje
+    const allLineage = segments.flatMap(s => s.lineage)
+
+    // 7. Retornar resultado puro
+    return {
+      segments: Object.freeze(segments),
+      lineage: Object.freeze(allLineage)
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error during segmentation'
+    throw new SegmentationError(`Failed to segment content: ${errorMessage}`, error)
+  }
+}
+

package/src/csl/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Types for CSL (Context Segmentation Layer) - Core Semántico
+ * 
+ * Solo tipos esenciales para CSL. Tipos relacionados con detección,
+ * anomalías y políticas van a ISL.
+ */
+
+/**
+ * OriginType represents the deterministic source of a content segment.
+ */
+export enum OriginType {
+  /**
+   * Direct user input from UI controls
+   * Always classified as UC (Untrusted Content) for security.
+   */
+  USER = 'USER',
+  
+  /**
+   * Content from visible DOM elements
+   * Classified as STC (Semi-Trusted Content) because user can verify it.
+   */
+  DOM_VISIBLE = 'DOM_VISIBLE',
+  
+  /**
+   * Content from hidden DOM elements
+   * Classified as UC (Untrusted Content) - potential attack vector.
+   */
+  DOM_HIDDEN = 'DOM_HIDDEN',
+  
+  /**
+   * Content from DOM attributes (data-*, aria-*, etc.)
+   * Classified as STC (Semi-Trusted Content) - visible in source.
+   */
+  DOM_ATTRIBUTE = 'DOM_ATTRIBUTE',
+  
+  /**
+   * Content injected by scripts (dynamically generated)
+   * Classified as UC (Untrusted Content) - can be manipulated.
+   */
+  SCRIPT_INJECTED = 'SCRIPT_INJECTED',
+  
+  /**
+   * Content fetched from network (API calls, external resources)
+   * Classified as UC (Untrusted Content) - external source, not verified.
+   */
+  NETWORK_FETCHED = 'NETWORK_FETCHED',
+  
+  /**
+   * System-generated content (instructions, system prompts, etc.)
+   * Classified as TC (Trusted Content) - system controls this content.
+   */
+  SYSTEM_GENERATED = 'SYSTEM_GENERATED',
+  
+  /**
+   * Origin cannot be determined
+   * Classified as UC (Untrusted Content) - unknown is untrusted by default.
+   */
+  UNKNOWN = 'UNKNOWN',
+}
+
+/**
+ * TrustLevelType represents the trust level of content
+ */
+export enum TrustLevelType {
+  TC = 'TC',   // Trusted Content
+  STC = 'STC', // Semi-Trusted Content
+  UC = 'UC',   // Untrusted Content
+}
+
+/**
+ * HashAlgorithm for ContentHash (opcional, para trazabilidad)
+ */
+export type HashAlgorithm = 'sha256' | 'sha512'
+
+/**
+ * Source type for CSL input
+ */
+export type Source = 'DOM' | 'UI' | 'SYSTEM' | 'API'
+
+/**
+ * CSLInput - Input para la función segment()
+ */
+export interface CSLInput {
+  readonly content: string
+  readonly source: Source
+  readonly metadata?: Record<string, unknown>
+}
+
+// Importar tipos de value objects para usar en interfaces
+import type { ContentHash, LineageEntry, TrustLevel } from './value-objects'
+
+/**
+ * CSLSegment - Segmento puro, solo datos semánticos
+ */
+export interface CSLSegment {
+  readonly id: string
+  readonly content: string              // Original, sin modificar
+  readonly source: Source
+  readonly trust: TrustLevel            // Clasificado por origen
+  readonly lineage: LineageEntry[]     // Inicializado en CSL
+  readonly hash?: ContentHash           // Opcional, para trazabilidad
+  readonly metadata?: Record<string, unknown>
+}
+
+/**
+ * CSLResult - Resultado puro, solo datos
+ */
+export interface CSLResult {
+  readonly segments: readonly CSLSegment[]
+  readonly lineage: readonly LineageEntry[]
+  readonly processingTimeMs?: number    // Opcional, para métricas
+}
+