s3-client-dtb 0.0.1 → 1.0.0

package/README.md

@@ -13,7 +13,7 @@ Almacena archivos directamente en el sistema de archivos de tu servidor. **Ideal
 - Cuando no necesitas un backend separado
 
 ### 🌐 Modo Cliente (StorageClient)  
-Se conecta a un backend remoto mediante HTTP. **Ideal para:
+Se conecta a un backend remoto mediante HTTP. **Ideal para:**
 - Producción con backend separado
 - Múltiples aplicaciones compartiendo almacenamiento
 - Escalabilidad y distribución
@@ -22,7 +22,10 @@ Se conecta a un backend remoto mediante HTTP. **Ideal para:
 
 - ✅ Almacenamiento local de archivos (StorageCore)
 - ✅ Cliente HTTP para backend remoto (StorageClient)
-- ✅ Autenticación con API keys
+- ✅ Autenticación con JWT y TOTP (Time-based OTP)
+- ✅ Generación automática de tokens con CLIENT_SECRET + TOTP
+- ✅ Configuración mediante variables de entorno
+- ✅ Tiempos de expiración configurables por cliente
 - ✅ Validación de tipos MIME
 - ✅ Límites de tamaño de archivo
 - ✅ Sanitización de rutas (protección contra path traversal)
@@ -47,13 +50,88 @@ npm install @nestjs/common
 
 ### Elegir el Modo Correcto
 
-**¿Necesitas almacenar archivos localmente?** → Usa `StorageCore`  
-**¿Necesitas conectarte a un backend remoto?** → Usa `StorageClient`
+**¿Necesitas almacenar archivos localmente?** → Usa `StorageCore` o modo `offline`  
+**¿Necesitas conectarte a un backend remoto?** → Usa `StorageClient` o modo `online`
 
 Ambos tienen la **misma API**, solo cambia la inicialización.
 
 ---
 
+## 🔄 Modo Offline/Online (Recomendado para desarrollo)
+
+El paquete soporta un **modo automático** que detecta si estás en desarrollo (offline) o producción (online) basándose en la variable de entorno `STORAGE_MODE`.
+
+### ¿Por qué usar esto?
+
+- **En desarrollo**: No necesitas tener un servidor de almacenamiento corriendo
+- **En producción**: Usa el servidor remoto sin cambiar código
+- **Mismo código**: La API es idéntica, solo cambian las variables de entorno
+
+### Configuración Rápida
+
+**Para desarrollo (offline):**
+```bash
+# .env
+STORAGE_MODE=offline
+STORAGE_ROOT_PATH=./uploads
+STORAGE_MAX_FILE_SIZE=50mb              # Opcional
+STORAGE_ALLOWED_MIME_TYPES=image/*,video/*  # Opcional
+```
+
+**Para producción (online):**
+```bash
+# .env
+STORAGE_MODE=online
+STORAGE_BASE_URL=https://storage.example.com
+STORAGE_CLIENT_ID=mi-app
+STORAGE_CLIENT_NAME=Mi Aplicacion
+STORAGE_PERMISSIONS=read,write,delete
+STORAGE_ALLOWED_PATHS=*
+STORAGE_CLIENT_SECRET=tu-clave-secreta...
+STORAGE_TOTP_SECRET=tu-semilla-totp...
+```
+
+### Uso en Código
+
+```typescript
+import 'dotenv/config';
+import { createClientFromConfig, isOfflineClient } from 's3-client-dtb';
+
+// ✅ Detecta automáticamente el modo según STORAGE_MODE
+const client = createClientFromConfig();
+
+// La API es idéntica en ambos modos
+const path = await client.uploadFile('images', buffer, 'image/png');
+const stream = await client.downloadFile(path);
+const exists = await client.fileExists(path);
+await client.deleteFile(path);
+
+// Si necesitas saber en qué modo estás:
+if (isOfflineClient(client)) {
+  console.log('Modo offline - archivos guardados localmente');
+} else {
+  console.log('Modo online - usando servidor remoto');
+}
+```
+
+### Funciones Auxiliares
+
+```typescript
+import {
+  createClientFromConfig,    // Detecta modo automáticamente
+  createOfflineClient,       // Forzar modo offline
+  createOnlineClient,        // Forzar modo online (deprecated, usa createClientFromConfig)
+  getStorageMode,            // Obtener el modo actual
+  isOfflineClient,           // Verificar si es cliente offline
+  isOnlineClient,            // Verificar si es cliente online
+} from 's3-client-dtb';
+
+// Obtener el modo configurado
+const mode = getStorageMode(); // 'online' | 'offline'
+```
+
+---
+
 ## 📁 Modo Local (StorageCore)
 
 ### Configuración
@@ -95,51 +173,363 @@ const exists = await storage.fileExists(path);
 
 ## 🌐 Modo Cliente (StorageClient)
 
-### Configuración
+### Configuración con Variables de Entorno
+
+El cliente se configura mediante variables de entorno. Crea un archivo `.env` basado en `.env.example`:
+
+```bash
+# Modo de almacenamiento (online para servidor remoto)
+STORAGE_MODE=online
+
+# Variables requeridas para modo online
+STORAGE_CLIENT_ID=mi-cliente-123
+STORAGE_CLIENT_NAME=Mi Aplicacion
+STORAGE_BASE_URL=http://localhost:3000
+STORAGE_PERMISSIONS=["read","write","delete"]
+STORAGE_ALLOWED_PATHS=["*"]
+STORAGE_CLIENT_SECRET=tu-clave-secreta-compartida-minimo-32-caracteres
+STORAGE_TOTP_SECRET=tu-semilla-totp-compartida-minimo-16-caracteres
+
+# Variables opcionales
+STORAGE_TOKEN_EXPIRES_IN=5m
+STORAGE_TOTP_PERIOD=30
+STORAGE_RATE_LIMIT_REQUESTS=1000
+STORAGE_RATE_LIMIT_WINDOW=1h
+```
+
+**IMPORTANTE**: 
+- Los valores de `STORAGE_CLIENT_SECRET` y `STORAGE_TOTP_SECRET` deben ser los mismos que están en las variables de entorno del servidor (`CLIENT_SECRET` y `TOTP_SECRET`).
+- Si el servidor usa `TOTP_PERIOD` distinto de 30, configura `STORAGE_TOTP_PERIOD` con el mismo valor (15–300 segundos).
+- Para `STORAGE_PERMISSIONS` y `STORAGE_ALLOWED_PATHS` puedes usar JSON array (`["read","write","delete"]`) o valores separados por comas (`read,write,delete`).
+
+### 🔗 Conectando con el Backend
+
+Para que el cliente se conecte correctamente al backend, necesitas asegurarte de que ciertos valores coincidan exactamente entre ambos.
+
+#### Checklist de Configuración
+
+Antes de usar el cliente, verifica que:
+
+- [ ] **`STORAGE_CLIENT_SECRET`** (cliente) = **`CLIENT_SECRET`** (servidor)
+- [ ] **`STORAGE_TOTP_SECRET`** (cliente) = **`TOTP_SECRET`** (servidor)
+- [ ] **`STORAGE_TOTP_PERIOD`** (cliente) = **`TOTP_PERIOD`** (servidor) - Si el servidor usa un valor distinto de 30
+- [ ] **`STORAGE_BASE_URL`** apunta a la URL correcta del servidor (ej: `http://localhost:3000`)
+
+#### Ejemplo de Configuración Completa
+
+**Backend (s3-package/.env):**
+```env
+CLIENT_SECRET=mi-clave-secreta-compartida-minimo-32-caracteres-1234567890
+TOTP_SECRET=mi-semilla-totp-compartida-minimo-16-caracteres
+TOTP_PERIOD=30
+PORT=3000
+```
+
+**Cliente (tu-app/.env):**
+```env
+STORAGE_CLIENT_ID=mi-cliente-123
+STORAGE_CLIENT_NAME=Mi Aplicacion
+STORAGE_BASE_URL=http://localhost:3000
+STORAGE_PERMISSIONS=["read","write","delete"]
+STORAGE_ALLOWED_PATHS=["*"]
+STORAGE_CLIENT_SECRET=mi-clave-secreta-compartida-minimo-32-caracteres-1234567890
+STORAGE_TOTP_SECRET=mi-semilla-totp-compartida-minimo-16-caracteres
+STORAGE_TOTP_PERIOD=30
+```
+
+**⚠️ Importante**: Los valores de `CLIENT_SECRET` y `TOTP_SECRET` deben ser **exactamente iguales** en ambos archivos `.env`.
+
+#### Verificar la Conexión
+
+Una vez configurado, puedes verificar que la conexión funciona correctamente:
+
+```typescript
+import 'dotenv/config';
+import { createClientFromConfig } from 's3-client-dtb';
+
+const client = createClientFromConfig();
+
+// Verificar que puedes generar códigos TOTP correctos
+try {
+  await client.verifyTotp();
+  console.log('✅ Conexión con el backend verificada correctamente');
+} catch (error) {
+  console.error('❌ Error al conectar con el backend:', error);
+  // Verifica que los secrets coincidan y que el servidor esté corriendo
+}
+```
+
+#### Solución de Problemas de Conexión
+
+**Error: "UNAUTHORIZED" o "TOTP_VERIFY_ERROR"**
+- Verifica que `STORAGE_CLIENT_SECRET` y `STORAGE_TOTP_SECRET` coincidan exactamente con los del servidor
+- Verifica que `STORAGE_TOTP_PERIOD` coincida con `TOTP_PERIOD` del servidor
+- Asegúrate de que el servidor esté corriendo y accesible en `STORAGE_BASE_URL`
+
+**Error: "Timeout al conectar con el servidor"**
+- Verifica que `STORAGE_BASE_URL` sea correcta y el servidor esté corriendo
+- Verifica la conectividad de red
+- Aumenta el `timeout` en la configuración manual si es necesario
+
+**Error: "FORBIDDEN"**
+- Verifica que los `STORAGE_PERMISSIONS` incluyan la operación que intentas realizar
+- Verifica que el `STORAGE_ALLOWED_PATHS` permita la ruta que intentas usar
+
+### Cargar Variables de Entorno
+
+Si usas Node.js, puedes usar `dotenv` para cargar el archivo `.env`:
+
+```bash
+npm install dotenv
+```
+
+```typescript
+import 'dotenv/config';
+import { createClientFromConfig } from 's3-client-dtb';
+
+const client = createClientFromConfig();
+```
+
+O cargar manualmente:
+
+```typescript
+import { config } from 'dotenv';
+config(); // Carga .env desde el directorio actual
+
+import { createClientFromConfig } from 's3-client-dtb';
+const client = createClientFromConfig();
+```
+
+### Crear Cliente desde Variables de Entorno
+
+```typescript
+import { createClientFromConfig } from 's3-client-dtb';
+
+// Lee las variables de entorno automáticamente
+const client = createClientFromConfig();
+```
+
+### Configuración Manual
 
 ```typescript
 import { StorageClient } from 's3-client-dtb';
+import type { ClientConfig } from 's3-client-dtb';
+
+const clientConfig: ClientConfig = {
+  clientId: 'mi-cliente-123',
+  name: 'Mi Aplicacion',
+  permissions: ['read', 'write', 'delete'],
+  allowedPaths: ['*'],
+  rateLimit: {
+    requests: 1000,
+    window: '1h'
+  },
+  tokenExpiresIn: '5m'
+};
 
-// ✅ Configuración simple - Solo necesitas URL y API key
 const client = new StorageClient({
-  baseUrl: 'https://api.midominio.com',  // URL del backend
-  apiKey: 'sk_live_xxx',                 // Tu API key
-  timeout: 30000                         // Opcional: timeout en ms
+  baseUrl: 'https://api.midominio.com',
+  clientConfig,
+  clientSecret: 'tu-clave-secreta-compartida-minimo-32-caracteres',
+  totpSecret: 'tu-semilla-totp-compartida-minimo-16-caracteres',
+  totpPeriodSeconds: 30, // opcional; debe coincidir con TOTP_PERIOD del servidor
 });
 ```
 
+### Autenticación Automática
+
+El cliente genera tokens automáticamente usando TOTP:
+
+```typescript
+import { createClientFromConfig } from 's3-client-dtb';
+
+const client = createClientFromConfig();
+
+// El cliente genera tokens automáticamente usando CLIENT_SECRET + TOTP
+// No necesitas llamar ningún método de autenticación manualmente
+
+// Opcional: Verificar que puedes generar códigos TOTP correctos
+await client.verifyTotp();
+
+// Ahora puedes usar el cliente normalmente
+// Los tokens se generan y renuevan automáticamente
+```
+
+### Variables de Entorno
+
+#### Requeridas
+
+- `STORAGE_CLIENT_ID` (string): Identificador único del cliente
+- `STORAGE_CLIENT_NAME` (string): Nombre descriptivo de la aplicación
+- `STORAGE_BASE_URL` (string): URL del backend (ej: `http://localhost:3000`)
+- `STORAGE_PERMISSIONS` (string): Permisos del cliente. Puede ser JSON array (`["read","write","delete"]`) o valores separados por comas (`read,write,delete`)
+- `STORAGE_ALLOWED_PATHS` (string): Paths permitidos. Puede ser JSON array (`["*"]` o `["images/*","documents/*"]`) o valores separados por comas (`*` o `images/*,documents/*`)
+- `STORAGE_CLIENT_SECRET` (string): Clave secreta compartida con el servidor (mínimo 32 caracteres)
+- `STORAGE_TOTP_SECRET` (string): Semilla TOTP compartida con el servidor (mínimo 16 caracteres)
+
+#### Opcionales
+
+- `STORAGE_TOKEN_EXPIRES_IN` (string): Duración del token JWT (ej: `"5m"`, `"1h"`, `"30m"`). Si no se especifica, se usa el default del servidor (`TOKEN_EXPIRES_IN`)
+- `STORAGE_TOTP_PERIOD` (number): Período TOTP en segundos (15–300, default 30). Debe coincidir con `TOTP_PERIOD` del servidor.
+- `STORAGE_RATE_LIMIT_REQUESTS` (number): Número de peticiones permitidas (solo se usa si también defines `STORAGE_RATE_LIMIT_WINDOW`)
+- `STORAGE_RATE_LIMIT_WINDOW` (string): Ventana de tiempo para el rate limit (ej: `"1h"`, `"30m"`). Solo se usa si también defines `STORAGE_RATE_LIMIT_REQUESTS`
+
+#### Tabla de Referencia Rápida
+
+| Variable | Requerida | Tipo | Default | Descripción |
+|----------|-----------|------|---------|-------------|
+| `STORAGE_CLIENT_ID` | ✅ | string | - | Identificador único del cliente |
+| `STORAGE_CLIENT_NAME` | ✅ | string | - | Nombre descriptivo de la aplicación |
+| `STORAGE_BASE_URL` | ✅ | string | - | URL del backend (ej: `http://localhost:3000`) |
+| `STORAGE_PERMISSIONS` | ✅ | string | - | Permisos: JSON array o comma-separated (`["read","write","delete"]` o `read,write,delete`) |
+| `STORAGE_ALLOWED_PATHS` | ✅ | string | - | Paths permitidos: JSON array o comma-separated (`["*"]` o `*`) |
+| `STORAGE_CLIENT_SECRET` | ✅ | string | - | Clave secreta compartida (mínimo 32 caracteres). **Debe coincidir con `CLIENT_SECRET` del servidor** |
+| `STORAGE_TOTP_SECRET` | ✅ | string | - | Semilla TOTP compartida (mínimo 16 caracteres). **Debe coincidir con `TOTP_SECRET` del servidor** |
+| `STORAGE_TOKEN_EXPIRES_IN` | ❌ | string | `5m` | Duración del token JWT (`30s`, `5m`, `1h`, `7d`) |
+| `STORAGE_TOTP_PERIOD` | ❌ | number | `30` | Período TOTP en segundos (15-300). **Debe coincidir con `TOTP_PERIOD` del servidor** |
+| `STORAGE_RATE_LIMIT_REQUESTS` | ❌ | number | - | Número de peticiones permitidas (requiere `STORAGE_RATE_LIMIT_WINDOW`) |
+| `STORAGE_RATE_LIMIT_WINDOW` | ❌ | string | - | Ventana de tiempo para rate limit (`1h`, `30m`, `7d`) |
+
 ### Ejemplos de baseUrl
 
 ```typescript
 // Con dominio
-new StorageClient({ baseUrl: 'https://api.midominio.com', apiKey: 'sk_xxx' });
+new StorageClient({ 
+  baseUrl: 'https://api.midominio.com',
+  clientConfig 
+});
 
 // Con IP directa
-new StorageClient({ baseUrl: 'http://192.168.1.100:3000', apiKey: 'sk_xxx' });
+new StorageClient({ 
+  baseUrl: 'http://192.168.1.100:3000',
+  clientConfig 
+});
 
 // Con puerto personalizado
-new StorageClient({ baseUrl: 'http://localhost:8080', apiKey: 'sk_xxx' });
+new StorageClient({ 
+  baseUrl: 'http://localhost:8080',
+  clientConfig 
+});
 ```
 
 ### Uso Completo
 
 ```typescript
-import { StorageClient } from 's3-client-dtb';
+import 'dotenv/config'; // Cargar variables de entorno
+import { createClientFromConfig } from 's3-client-dtb';
+import { 
+  FileNotFoundError, 
+  UploadError, 
+  StorageError 
+} from 's3-client-dtb';
 import { readFileSync } from 'fs';
 
-const client = new StorageClient({
-  baseUrl: 'https://api.midominio.com',
-  apiKey: 'sk_live_xxx'
-});
+// Inicializar cliente desde variables de entorno
+const client = createClientFromConfig();
 
-// ⚠️ IMPORTANTE: La API es IDÉNTICA a StorageCore
-const buffer = readFileSync('./mi-imagen.jpg');
-const path = await client.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
-const stream = await client.downloadFile(path);
-const metadata = await client.getFileMetadata(path);
-const { files, total } = await client.listFiles('images');
-await client.deleteFile(path);
-const exists = await client.fileExists(path);
+// Opcional: Verificar que la configuración TOTP es correcta
+try {
+  await client.verifyTotp();
+  console.log('✅ Cliente configurado correctamente');
+} catch (error) {
+  console.error('❌ Error en configuración:', error);
+  process.exit(1);
+}
+
+// Ejemplo: Subir un archivo
+try {
+  const buffer = readFileSync('./mi-imagen.jpg');
+  const path = await client.uploadFile(
+    'images/photo.jpg',  // Ruta donde se guardará
+    buffer,              // Buffer del archivo
+    'image/jpeg'         // Tipo MIME
+  );
+  console.log('✅ Archivo subido en:', path);
+} catch (error) {
+  if (error instanceof UploadError) {
+    console.error('❌ Error al subir:', error.message);
+  } else {
+    console.error('❌ Error inesperado:', error);
+  }
+}
+
+// Ejemplo: Descargar un archivo
+try {
+  const stream = await client.downloadFile('images/photo.jpg');
+  
+  // Convertir stream a buffer si es necesario
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(chunk);
+  }
+  const downloadedBuffer = Buffer.concat(chunks);
+  console.log('✅ Archivo descargado:', downloadedBuffer.length, 'bytes');
+} catch (error) {
+  if (error instanceof FileNotFoundError) {
+    console.error('❌ Archivo no encontrado');
+  } else {
+    console.error('❌ Error al descargar:', error);
+  }
+}
+
+// Ejemplo: Obtener metadata
+try {
+  const metadata = await client.getFileMetadata('images/photo.jpg');
+  console.log('Metadata:', {
+    nombre: metadata.name,
+    tamaño: metadata.size,
+    tipo: metadata.mimeType,
+    creado: metadata.createdAt
+  });
+} catch (error) {
+  console.error('❌ Error al obtener metadata:', error);
+}
+
+// Ejemplo: Listar archivos
+try {
+  const { files, total } = await client.listFiles('images', {
+    limit: 10,      // Máximo 10 archivos
+    offset: 0,      // Desde el inicio
+    prefix: 'photo'  // Solo archivos que empiecen con "photo"
+  });
+  console.log(`✅ Encontrados ${files.length} de ${total} archivos`);
+  files.forEach(file => {
+    console.log(`  - ${file.name} (${file.size} bytes)`);
+  });
+} catch (error) {
+  console.error('❌ Error al listar archivos:', error);
+}
+
+// Ejemplo: Verificar existencia
+const exists = await client.fileExists('images/photo.jpg');
+console.log('Archivo existe:', exists);
+
+// Ejemplo: Eliminar archivo
+try {
+  await client.deleteFile('images/photo.jpg');
+  console.log('✅ Archivo eliminado');
+} catch (error) {
+  if (error instanceof FileNotFoundError) {
+    console.error('❌ Archivo no encontrado para eliminar');
+  } else {
+    console.error('❌ Error al eliminar:', error);
+  }
+}
+```
+
+### Gestión de Tokens
+
+El cliente genera tokens automáticamente usando TOTP:
+
+- **Generación automática**: El cliente genera tokens JWT usando `CLIENT_SECRET + TOTP_CODE`
+- **TOTP dinámico**: El código TOTP cambia cada 30 segundos, proporcionando seguridad adicional
+- **Renovación automática**: Los tokens se regeneran automáticamente cuando expiran o cuando cambia el código TOTP
+- **Caché inteligente**: Los tokens se cachean y se regeneran solo cuando es necesario
+- **Errores 401**: El cliente regenera el token automáticamente si recibe un 401
+
+```typescript
+// El cliente siempre está listo para usar, genera tokens automáticamente
+// No necesitas métodos de autenticación manual
 ```
 
 ---
@@ -151,20 +541,23 @@ Como ambos tienen la misma API, cambiar de modo es **súper simple**:
 ### Opción 1: Variable de Entorno
 
 ```typescript
-import { StorageCore, StorageClient } from 's3-client-dtb';
+import { StorageCore, createClientFromConfig } from 's3-client-dtb';
 
 // Usar variable de entorno para decidir el modo
 const useRemote = process.env.STORAGE_MODE === 'remote';
 
 const storage = useRemote
-  ? new StorageClient({
-      baseUrl: process.env.STORAGE_URL!,
-      apiKey: process.env.STORAGE_API_KEY!
-    })
+  ? createClientFromConfig() // Lee variables de entorno automáticamente
   : new StorageCore({
       rootPath: process.env.STORAGE_PATH || './uploads'
     });
 
+// Si es remoto, el cliente genera tokens automáticamente
+// Opcional: Verificar TOTP
+if (useRemote && storage instanceof StorageClient) {
+  await storage.verifyTotp();
+}
+
 // El resto del código es idéntico
 await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
 ```
@@ -172,15 +565,18 @@ await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
 ### Opción 2: Factory Function
 
 ```typescript
-import { StorageCore, StorageClient } from 's3-client-dtb';
-
-function createStorage() {
-  if (process.env.STORAGE_URL && process.env.STORAGE_API_KEY) {
-    // Modo remoto
-    return new StorageClient({
-      baseUrl: process.env.STORAGE_URL,
-      apiKey: process.env.STORAGE_API_KEY
-    });
+import { StorageCore, createClientFromConfig } from 's3-client-dtb';
+
+async function createStorage() {
+  if (process.env.STORAGE_URL) {
+    // Modo remoto - usa variables de entorno
+    const client = createClientFromConfig();
+    
+    // El cliente genera tokens automáticamente
+    // Opcional: Verificar TOTP
+    await client.verifyTotp();
+    
+    return client;
   }
   
   // Modo local (por defecto)
@@ -189,35 +585,12 @@ function createStorage() {
   });
 }
 
-const storage = createStorage();
+const storage = await createStorage();
 // Usar normalmente
 await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
 ```
 
-### Opción 3: TypeScript con Interfaz Común
-
-```typescript
-import { StorageCore, StorageClient } from 's3-client-dtb';
-import type { FileMetadata, ListFilesOptions } from 's3-client-dtb';
-
-// Interfaz común para ambos modos
-interface Storage {
-  uploadFile(path: string, buffer: Buffer, mimeType: string, prefix?: string): Promise<string>;
-  downloadFile(path: string): Promise<Readable>;
-  deleteFile(path: string): Promise<void>;
-  getFileMetadata(path: string): Promise<FileMetadata>;
-  listFiles(directoryPath?: string, options?: ListFilesOptions): Promise<{files: FileMetadata[], total: number}>;
-  fileExists(path: string): Promise<boolean>;
-}
-
-// Crear instancia según configuración
-const storage: Storage = process.env.STORAGE_MODE === 'remote'
-  ? new StorageClient({ baseUrl: process.env.STORAGE_URL!, apiKey: process.env.STORAGE_API_KEY! })
-  : new StorageCore({ rootPath: './uploads' });
-
-// Código tipo-seguro
-await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
-```
+---
 
 ## Uso desde NestJS
 
@@ -282,6 +655,8 @@ export class FilesService {
 }
 ```
 
+---
+
 ## 📖 API Completa
 
 ### ⚡ Métodos Comunes (Ambos Modos)
@@ -325,84 +700,40 @@ interface StorageCoreOptions {
 #### StorageClient (Modo Remoto)
 
 ```typescript
+// Opción 1: Desde variables de entorno (recomendado)
+createClientFromConfig(): StorageClient
+
+// Opción 2: Manual
 new StorageClient(options: StorageClientOptions)
 
 interface StorageClientOptions {
-  baseUrl: string;    // URL del backend: "https://api.com" o "http://192.168.1.100:3000"
-  apiKey: string;      // API key: "sk_live_xxx"
-  timeout?: number;    // Opcional: timeout en ms (default: 30000)
+  baseUrl: string;                // URL del backend
+  clientConfig: ClientConfig;     // Configuración del cliente
+  clientSecret: string;           // Clave secreta compartida (mínimo 32 caracteres). Debe coincidir con CLIENT_SECRET del servidor
+  totpSecret: string;             // Semilla TOTP compartida (mínimo 16 caracteres). Debe coincidir con TOTP_SECRET del servidor
+  totpPeriodSeconds?: number;      // Opcional: Período TOTP en segundos (15-300, default: 30). Debe coincidir con TOTP_PERIOD del servidor
+  timeout?: number;               // Opcional: timeout en ms (default: 30000)
 }
-```
-
-**Nota:** El cliente automáticamente agrega el prefijo `/apifiles` a las URLs y maneja la autenticación con API keys.
-
-#### Constructor
 
-```typescript
-new StorageCore(options: StorageCoreOptions)
+interface ClientConfig {
+  clientId: string;
+  name: string;
+  permissions: ('read' | 'write' | 'delete')[];
+  allowedPaths: string[];
+  rateLimit?: {
+    requests: number;
+    window: string;
+  };
+  tokenExpiresIn?: string;   // Opcional: "30m", "1h", "5m", "7d"
+}
 ```
 
-**Opciones:**
-- `rootPath` (string, requerido): Ruta raíz donde se almacenarán los archivos
-- `maxFileSize` (string, opcional): Tamaño máximo de archivo (ej: "50mb", "1gb"). Por defecto: "50mb"
-- `allowedMimeTypes` (string[], opcional): Tipos MIME permitidos (ej: ["image/*", "video/*"]). Por defecto: ["*"]
-
-#### Métodos
-
-##### `uploadFile(path, buffer, mimeType, prefix?)`
-
-Sube un archivo al almacenamiento.
-
-- `path` (string): Ruta relativa donde se guardará el archivo
-- `buffer` (Buffer): Contenido del archivo
-- `mimeType` (string): Tipo MIME del archivo
-- `prefix` (string, opcional): Prefijo para el nombre del archivo (se genera un UUID)
-
-**Retorna:** `Promise<string>` - Ruta relativa del archivo guardado
-
-##### `downloadFile(path)`
-
-Descarga un archivo como stream.
-
-- `path` (string): Ruta relativa del archivo
-
-**Retorna:** `Promise<Readable>` - Stream de Node.js
-
-##### `deleteFile(path)`
-
-Elimina un archivo.
-
-- `path` (string): Ruta relativa del archivo
-
-**Retorna:** `Promise<void>`
-
-##### `getFileMetadata(path)`
-
-Obtiene metadata de un archivo.
-
-- `path` (string): Ruta relativa del archivo
-
-**Retorna:** `Promise<FileMetadata>`
-
-##### `listFiles(directoryPath?, options?)`
-
-Lista archivos en un directorio.
-
-- `directoryPath` (string, opcional): Ruta del directorio (vacío para raíz)
-- `options` (ListFilesOptions, opcional):
-  - `limit` (number): Número máximo de archivos
-  - `offset` (number): Offset para paginación
-  - `prefix` (string): Filtrar por prefijo en el nombre
-
-**Retorna:** `Promise<{ files: FileMetadata[], total: number }>`
-
-##### `fileExists(path)`
-
-Verifica si un archivo existe.
+**Nota:** 
+- El cliente automáticamente agrega el prefijo `/apifiles` a las URLs
+- Genera tokens automáticamente usando `CLIENT_SECRET + TOTP` (no requiere autenticación manual)
+- Regenera tokens automáticamente cuando expiran o cuando cambia el código TOTP
 
-- `path` (string): Ruta relativa del archivo
-
-**Retorna:** `Promise<boolean>`
+---
 
 ## Tipos
 
@@ -420,32 +751,41 @@ interface FileMetadata {
 }
 ```
 
+### ListFilesOptions
+
+```typescript
+interface ListFilesOptions {
+  limit?: number;
+  offset?: number;
+  prefix?: string;
+}
+```
+
+---
+
 ## 📋 Comparación Rápida
 
 | Característica | StorageCore (Local) | StorageClient (Remoto) |
 |---------------|---------------------|------------------------|
-| **Inicialización** | `new StorageCore({ rootPath })` | `new StorageClient({ baseUrl, apiKey })` |
+| **Inicialización** | `new StorageCore({ rootPath })` | `createClientFromConfig()` o `new StorageClient({ baseUrl, clientConfig })` |
 | **Almacenamiento** | Sistema de archivos local | Backend remoto vía HTTP |
 | **API** | ✅ Idéntica | ✅ Idéntica |
-| **Autenticación** | ❌ No requiere | ✅ Requiere API key |
+| **Autenticación** | ❌ No requiere | ✅ Genera tokens JWT con TOTP (automático) |
+| **Configuración** | Opciones en constructor | Variables de entorno |
+| **Tiempos de expiración** | ❌ No aplica | ✅ Configurables mediante variables de entorno |
 | **Ideal para** | Desarrollo, mismo servidor | Producción, múltiples apps |
-| **Configuración** | Solo ruta | URL + API key |
+
+---
 
 ## 💡 Recomendaciones
 
 - **Desarrollo**: Usa `StorageCore` con `rootPath: './uploads'`
-- **Producción**: Usa `StorageClient` con variables de entorno
+- **Producción**: Usa `StorageClient` con variables de entorno y autenticación OTP
 - **Cambio fácil**: Ambos tienen la misma API, solo cambia la inicialización
+- **Seguridad**: El cliente renueva tokens automáticamente según los tiempos configurados
+- **Configuración**: Usa `createClientFromConfig()` para leer automáticamente las variables de entorno
 
-### ListFilesOptions
-
-```typescript
-interface ListFilesOptions {
-  limit?: number;
-  offset?: number;
-  prefix?: string;
-}
-```
+---
 
 ## Errores
 
@@ -459,6 +799,7 @@ El paquete lanza errores personalizados que extienden `StorageError`:
 - `DeleteError`: Error al eliminar archivo
 - `MetadataError`: Error al obtener metadata
 - `ListError`: Error al listar archivos
+- `StorageError`: Error genérico
 
 Todos los errores tienen una propiedad `code` para identificación:
 
@@ -474,10 +815,49 @@ try {
 
 ## Seguridad
 
+- **Autenticación JWT con OTP**: Sistema seguro de autenticación de dos factores
+- **Renovación automática de tokens**: Configurable por cliente mediante variables de entorno
+- **Validación en cadena**: Cada refresh token valida el anterior
 - **Sanitización de rutas**: Protección contra path traversal (`..`)
 - **Validación de caracteres**: Solo permite caracteres seguros en rutas
 - **Validación de MIME types**: Verifica tipos de archivo permitidos
 - **Límites de tamaño**: Previene archivos demasiado grandes
+- **Permisos granulares**: Cada cliente tiene permisos específicos (read, write, delete)
+- **Paths permitidos**: Cada cliente solo puede acceder a paths configurados
+
+## Ejemplo Completo con Variables de Entorno
+
+1. **Crear archivo `.env`:**
+   ```bash
+   STORAGE_CLIENT_ID=mi-app-prod
+   STORAGE_CLIENT_NAME=Mi Aplicacion
+   STORAGE_BASE_URL=http://localhost:3000
+   STORAGE_PERMISSIONS=["read","write","delete"]
+   STORAGE_ALLOWED_PATHS=["*"]
+   STORAGE_CLIENT_SECRET=tu-clave-secreta-compartida-minimo-32-caracteres
+   STORAGE_TOTP_SECRET=tu-semilla-totp-compartida-minimo-16-caracteres
+   STORAGE_TOKEN_EXPIRES_IN=5m
+   STORAGE_TOTP_PERIOD=30
+   STORAGE_RATE_LIMIT_REQUESTS=1000
+   STORAGE_RATE_LIMIT_WINDOW=1h
+   ```
+
+2. **Usar el cliente:**
+   ```typescript
+   import 'dotenv/config'; // Cargar variables de entorno
+   import { createClientFromConfig } from 's3-client-dtb';
+   import { readFileSync } from 'fs';
+
+   const client = createClientFromConfig(); // Lee variables de entorno
+
+   // El cliente genera tokens automáticamente
+   // Opcional: Verificar TOTP
+   await client.verifyTotp();
+
+   // Usar normalmente
+   const buffer = readFileSync('./imagen.jpg');
+   const path = await client.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
+   ```
 
 ## Licencia