Módulo	Maven Central
network-core
network-ktor
network-ws-core
network-ws-ktor
security-core
sample-api

SDK Kotlin Multiplatform para Acceso Remoto Seguro de Datos

Una librería Kotlin Multiplatform (KMP) reutilizable y modular diseñada para proveer una base segura, escalable y agnóstica de transporte para operaciones de datos remotos en aplicaciones Android e iOS.

• Documentación
• Quick Start
• Instalación
• Resumen
• Objetivos del Proyecto
• Arquitectura
• Estructura de Módulos
• Requisitos
• Roadmap
• Seguridad — OWASP MASVS
• Reglas de Diseño

• Guía de Integración — Paso a paso completo: dependencias, configuración, capa data (todos los métodos HTTP, paginación, filtros, body JSON, 204 No Content), consumo de resultados, RequestContext, ResponseInterceptor, autenticación (simple y con sesión completa), certificate pinning, observabilidad, multi-entorno, y manejo de errores — todo con escenarios de negocio explicados
• Guía Rápida para Android — Primeros pasos para desarrolladores Android: contrato, adapter, DI (Hilt/Koin), NetworkResult, errores, auth, config, logging, paginación, retry por endpoint, y FAQ de seguridad
• Guía Rápida para iOS — Primeros pasos para desarrolladores iOS: protocolo, adapter, DI, NetworkResult, errores, auth, config, logging, paginación, retry por endpoint, y FAQ de seguridad
• Integración con Clean Architecture — Cómo usar el SDK exclusivamente en la capa data: estructura de carpetas, DTOs vs modelos de dominio, DataSource, Repository, DI, y referencias a escenarios avanzados
• Guía de Integración WebSocket — Servidor — Protocolo WebSocket, tecnologías de servidor (Ktor, Spring, Node.js, Go, Python, .NET), servicios cloud administrados, patrones de comunicación, seguridad, y compatibilidad con el SDK

• network-core — Abstracciones puras de red, pipeline de ejecución, taxonomía de errores
• network-ktor — Adaptador de transporte HTTP basado en Ktor
• network-ws-core — Abstracciones puras de WebSocket, pipeline de conexión, reconexión, errores
• network-ws-ktor — Adaptador de transporte WebSocket basado en Ktor
• security-core — Credenciales, sesiones, almacenamiento seguro, confianza TLS, sanitización de logs
• sample-api — Módulo piloto de referencia para integración de API de dominio

• Índice de ADRs
• ADR-001: Separación network-core / security-core
• ADR-002: Contratos primero, implementación después
• ADR-003: Sin detalles de transporte en API pública
• ADR-004: Separación commonMain / platformMain
• ADR-005: Pipeline de ejecución segura centralizado
• ADR-006: Clasificación de errores centralizada

• Índice de Diagramas
• 01 — Arquitectura General
• 02 — Dependencias entre Módulos
• 03 — Flujo de Ejecución de Requests
• 04 — Estrategia KMP
• 05 — Relaciones entre Contratos

// 1. Crea el repository (configuración por defecto incluida)
val repository = SampleApiFactory.create()

// 2. Llama un endpoint
val result: NetworkResult<List<User>> = repository.getUsers()

// 3. Maneja el resultado
result.fold(
    onSuccess = { users ->
        users.forEach { println("${it.displayName} (@${it.handle})") }
    },
    onFailure = { error ->
        println("Error: ${error.message}")
    }
)

SampleApiFactory.create() ensambla internamente todo el pipeline: configuración → engine HTTP → executor con reintentos → data source → repository. Tú solo interactúas con UserRepository y NetworkResult<User>.

Para configuración avanzada (auth, timeouts personalizados, interceptors), consulta la Guía de Integración o las guías rápidas para Android / iOS.

El SDK está publicado en Maven Central. Agrega los módulos que necesites en tu build.gradle.kts:

repositories {
    mavenCentral()
}

dependencies {
    // Contratos core (siempre requeridos)
    implementation("io.github.dancrrdz93:network-core:0.4.0")

    // Implementación de transporte HTTP (elige uno)
    implementation("io.github.dancrrdz93:network-ktor:0.4.0")

    // WebSocket (si necesitas conexiones persistentes bidireccionales)
    implementation("io.github.dancrrdz93:network-ws-core:0.4.0")
    implementation("io.github.dancrrdz93:network-ws-ktor:0.4.0")

    // Seguridad (auth, almacenamiento seguro, gestión de sesiones)
    implementation("io.github.dancrrdz93:security-core:0.4.0")

    // Módulo de referencia (opcional — para ver el patrón de integración)
    implementation("io.github.dancrrdz93:sample-api:0.4.0")
}

Si el SDK se consume como módulo local (composite build), usa implementation(project(":network-core")) en su lugar.

Core Data Platform es un SDK interno construido con Kotlin Multiplatform que provee una base unificada, segura y extensible para hacer llamadas a APIs remotas desde aplicaciones móviles. Está diseñado para ser consumido por múltiples apps a gran escala sin acoplarlas a ningún cliente HTTP, librería de serialización o contrato de backend específico.

En organizaciones que mantienen múltiples aplicaciones móviles, cada equipo tiende a construir su propio stack de networking y seguridad. Esto lleva a:

• Infraestructura duplicada — lógica de reintentos, manejo de errores y flujos de auth reimplementados por app.
• Manejo de errores inconsistente — cada app clasifica y muestra errores de forma diferente.
• Fragmentación de seguridad — almacenamiento de credenciales, sanitización de logs y políticas TLS varían entre equipos.
• Testing difícil — código de networking fuertemente acoplado hace que el unit testing sea costoso.

Core Data Platform resuelve esto proveyendo una única base bien testeada y dirigida por contratos que todas las apps comparten, manteniendo cada app libre de definir su propia lógica de dominio, serialización y UI.

• Organizaciones móviles multi-app (banca, fintech, seguros, retail, salud)
• Equipos adoptando Kotlin Multiplatform para lógica de negocio compartida
• Cualquier proyecto que necesite una separación limpia entre infraestructura de transporte y lógica de dominio

La arquitectura sigue tres principios fundamentales:

1. Contratos sobre implementaciones — Cada componente principal se define como una interfaz o clase abstracta en commonMain. Las implementaciones concretas se inyectan, nunca se hardcodean.

2. Separación por capas — El proyecto separa qué hace el SDK (contratos) de cómo lo hace (implementaciones) y quién lo usa (módulos de dominio).

3. Cero acoplamiento lateral — network-core y security-core son módulos completamente independientes. Ninguno sabe que el otro existe. Solo se componen en el punto de consumo (módulos de dominio o la app).

Estos módulos abordan preocupaciones fundamentalmente diferentes:

• network-core responde: "¿Cómo ejecuto, valido, reintento y clasifico operaciones HTTP de forma segura?"
• security-core responde: "¿Cómo almaceno secretos, gestiono sesiones, evalúo confianza y protejo datos sensibles?"

Mantenerlos independientes significa:

• Un módulo que solo necesita almacenamiento seguro no trae dependencias HTTP.
• Un módulo que solo necesita networking no trae dependencias de seguridad.
• El punto de integración (inyección de credenciales en headers HTTP) se maneja con un mapper ligero (CredentialHeaderMapper) que vive en security-core y retorna un simple Map<String, String> — sin tipos de red requeridos.

┌──────────────────────────────────────────────────────────────┐
│                      YOUR APPLICATION                        │
│                                                              │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
│   │ Feature A│  │ Feature B│  │ Feature C│  ← App layers     │
│   └────┬─────┘  └─────┬────┘  └──────┬───┘                   │
│        │              │              │                       │
│   ┌────▼──────────────▼──────────────▼────┐                  │
│   │        Domain API Modules             │  ← :payments-api │
│   │   (DTOs, Mappers, DataSources, Repos) │     :loyalty-api │
│   └────┬──────────────┬──────────────┬────┘     :users-api   │
│        │              │              │                       │
├────────┼──────────────┼──────────────┼───────────────────────┤
│        ▼              ▼              ▼                       │
│   ┌──────────┐  ┌────────────┐  ┌──────────────┐             │
│   │ network  │  │  network   │  │  security    │  ← SDK      │
│   │  -core   │  │   -ktor    │  │   -core      │             │
│   └──────────┘  └────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────┘

Los módulos del SDK se sitúan en la parte inferior del grafo de dependencias. Las funcionalidades de la aplicación nunca importan Ktor, nunca ven RawResponse, y nunca manejan lógica de reintentos directamente.

Implementaciones de plataforma en :security-core:

• AndroidSecretStore — DataStore + Cipher(AES/GCM/NoPadding) + Android Keystore
• IosSecretStore — Keychain Services (kSecClassGenericPassword)
• DefaultSessionController — Gestión de sesión con StateFlow, persistencia en SecretStore, refresh configurable
• DefaultCredentialProvider — Lee credencial activa desde SessionController.state

Para el detalle completo de cada módulo (tablas Expone/NO expone, contratos internos, decisiones de diseño), consulta los READMEs de Módulos.

:sample-api ──▶ :network-core
:sample-api ──▶ :network-ktor ──▶ :network-core
:sample-api ──▶ :security-core

:network-ktor ──▶ :network-core
:network-ktor ──▶ :security-core

:network-ws-ktor ──▶ :network-ws-core
:network-ws-ktor ──▶ :security-core

:network-core ──▶ (ninguno)
:network-ws-core ──▶ (ninguno)
:security-core ──▶ (ninguno)

Invariante crítica: :network-core, :network-ws-core y :security-core tienen cero dependencia mutua. Esto es por diseño y debe preservarse.

El 95%+ del código vive en commonMain. Solo SecretStore (Android Keystore / iOS Keychain) y los engines de transporte HTTP (OkHttp / Darwin) requieren source sets de plataforma. Para más detalle, consulta la Estrategia KMP.

Para guías detalladas de integración, configuración y uso:

• Android → Guía Rápida para Android
• iOS → Guía Rápida para iOS
• Integración paso a paso → Guía de Integración
• Clean Architecture → Integración con Clean Architecture

Para detalles técnicos de cada módulo (contratos, decisiones de diseño, extensibilidad, manejo de errores, seguridad):

• network-core — Pipeline de ejecución, errores, observabilidad
• network-ktor — Transporte HTTP, certificate pinning
• network-ws-core — Pipeline WebSocket, reconexión, errores
• network-ws-ktor — Transporte WebSocket, certificate pinning
• security-core — Credenciales, sesiones, almacenamiento seguro, TrustPolicy
• sample-api — Módulo de referencia

Para diagramas de arquitectura, consulta el índice de diagramas.

El SDK implementa guardrails de seguridad alineados al OWASP Mobile Application Security Verification Standard (MASVS). Consulta docs/security-checklist.md para el checklist completo.

El camino seguro es el camino por defecto. Los guardrails están activos sin configuración. Desactivarlos requiere acción explícita (allowInsecureConnections, sanitizer custom).

Estas son las invariantes arquitectónicas del proyecto. Todas las contribuciones deben respetarlas.

1. El API público nunca expone detalles de transporte. Los consumidores ven HttpRequest, NetworkResult, NetworkError. Nunca io.ktor.*, okhttp3.*, ni NSURLSession.

2. network-core y security-core nunca deben depender el uno del otro. Solo se integran a nivel del consumidor vía composición. Excepción: network-ktor depende de security-core para configurar certificate pinning via TrustPolicy.

3. Los errores son valores, no excepciones. NetworkResult.Failure envuelve NetworkError. Las excepciones se capturan en el límite del executor y se clasifican en tipos semánticos.

4. Diagnostic es interno. message es público. error.message es seguro para usuarios finales. error.diagnostic es solo para logging y debugging.

5. Las decisiones de reintento pertenecen al modelo de error. NetworkError.isRetryable determina la reintentabilidad. El executor no hardcodea qué errores reintentar.

6. Los interceptors son para infraestructura, no lógica de negocio. Headers de auth, contexto de tracing, logging — sí. Validación de órdenes, cálculo de precios — no.

7. DTOs y modelos de dominio siempre están separados. Los DTOs tienen @Serializable y coinciden con el contrato del API. Los modelos de dominio son limpios y agnósticos del API.

8. El código específico de plataforma vive en los bordes. Interfaces en commonMain. Implementaciones en androidMain/iosMain. Nunca al revés.

9. Cada componente principal es inyectable. HttpEngine, ErrorClassifier, ResponseValidator, CredentialProvider, SecretStore — todas interfaces, todas inyectadas vía constructor.

10. Las nuevas funcionalidades son aditivas. Nuevos módulos, nuevos interceptors, nuevos observers, nuevos subtipos de error. Los contratos existentes son estables.

Core Data Platform — Construido para equipos que envían múltiples apps desde una base compartida.