# 02 — Seguridad, Autenticación y Cifrado
## Estándar obligatorio de cookies HTTP-only, middleware Next.js y encriptación Kong

> **Uso:** Esta guía define las directrices y mecanismos de protección obligatorios para evitar fugas de información, proteger sesiones de usuario y asegurar transacciones.

---

## 1. Protección de Rutas (Autenticación Server-Side)

El frontend protege páginas y layouts directamente en el servidor utilizando el middleware `serverRequireAuth` antes de renderizar la interfaz. Esto previene el parpadeo de pantallas ("flash of unauthenticated content") y asegura que ningún Server Component exponga datos no autorizados.

### 1.1 Proteger un Server Component (Page / Layout):
```typescript
import { serverRequireAuth } from '@/lib/auth/middleware';

export default async function DashboardPage() {
  // 1. Invocar obligatoriamente en la cabecera
  const user = await serverRequireAuth(); // Redirige a /login si falla la sesión

  // 2. Si pasa, renderizamos de forma segura con los datos del usuario
  return (
    <main className="p-6">
      <h1>Bienvenido al Portal Seguro, {user.name}</h1>
      <p>ID de usuario verificado: {user.id}</p>
    </main>
  );
}
```

### 1.2 Chequeo de Autenticación Opcional:
Si deseas validar si el usuario está autenticado pero sin forzar la redirección (ej. en la Landing Page pública):
```typescript
import { checkAuth } from '@/lib/auth/middleware';

export default async function LandingPage() {
  const { isAuthenticated, user } = await checkAuth();

  return (
    <nav>
      {isAuthenticated ? (
        <span>Hola, {user?.name}</span>
      ) : (
        <a href="/login">Iniciar Sesión</a>
      )}
    </nav>
  );
}
```

---

## 2. Almacenamiento Seguro de Sesión (HTTP-only Cookies)

Queda **estrictamente prohibido** almacenar tokens JWT, contraseñas o datos de sesión en `localStorage` o `sessionStorage`. El navegador es vulnerable a ataques XSS y robo de tokens en estos alcances.

### Directrices de Cookies:
1. **`access_token`** y **`refresh_token`** deben configurarse en el backend o en el Route Handler de Next.js como:
   - `httpOnly: true` (Evita acceso por scripts JS).
   - `secure: true` (Viaja solo por HTTPS — desactivado solo en localhost).
   - `sameSite: 'strict'` (Mitigación completa de CSRF).
   - `path: '/'` (Válido para todo el dominio).

---

## 3. Cifrado Perimetral de Datos (Kong Gateway)

Para cualquier dato altamente sensible en tránsito en el cliente (como números de cuenta de ahorros, saldos o datos personales) que no queramos que sea interceptado o inspeccionado en las herramientas de desarrollo del navegador, aplicaremos el cifrado Kong perimetral.

Utilizamos las funciones integradas en `lib/cypher/encrypt.ts` y `lib/cypher/decrypt.ts`:

### 3.1 Cifrar datos en el cliente antes de enviar:
```typescript
import { kongEncrypt } from '@/lib/cypher/encrypt';

function ConfirmarTransaccion() {
  const enviarMontoSeguro = () => {
    const cuentaOrigenCifrada = kongEncrypt('0102-1234-56-1234567890');
    
    // El payload viajará cifrado y será descifrado en el Gateway Kong o en el Backend
    apiCall('/api/transferencia', {
      cuentaOrigen: cuentaOrigenCifrada
    });
  };
}
```

### 3.2 Descifrar datos en el servidor/cliente tras recibirlos:
```typescript
import { kongDecrypt } from '@/lib/cypher/decrypt';

function DetalleCuenta({ cuentaEncriptada }: { cuentaEncriptada: string }) {
  // Descifrar para visualización del usuario final
  const numeroCuentaReal = kongDecrypt(cuentaEncriptada);

  return (
    <div>
      <p>Número de cuenta: {numeroCuentaReal}</p>
    </div>
  );
}
```

---

## 4. Reglas de Oro de Seguridad en Frontend
- **Secrets de Entorno:** Nunca commitees archivos `.env.local` con secretos de producción reales. Las variables de servidor de Next.js (sin prefijo `NEXT_PUBLIC_`) son inaccesibles para el cliente. Úsalas para llaves privadas de cifrado o tokens de backend.
- **Sanitización de Inputs:** Valida y sanitiza todos los datos ingresados por el usuario utilizando esquemas robustos (Zod o TypeScript estricto) antes de renderizarlos en la UI para prevenir inyecciones HTML/React.