# Documentación de uso de microwd.online — v1.2

## Índice

1. [¿Qué es microwd.online?](#1-qué-es-microwdonline)
2. [Conceptos básicos de Stellar](#2-conceptos-básicos-de-stellar)
3. [Roles del sistema](#3-roles-del-sistema)
4. [Registrar un documento](#4-registrar-un-documento)
5. [Verificar un documento](#5-verificar-un-documento)
6. [Autenticación en la API](#6-autenticación-en-la-api)
7. [Gestión de usuarios](#7-gestión-de-usuarios)
8. [Panel de administración](#8-panel-de-administración)
9. [Uso programático de la API](#9-uso-programático-de-la-api)
10. [Monitorización y estado](#10-monitorización-y-estado)
11. [Seguridad](#11-seguridad)
12. [Backup y recuperación](#12-backup-y-recuperación)
13. [Preguntas frecuentes](#13-preguntas-frecuentes)

---

## 1. ¿Qué es microwd.online?

**microwd.online** es un servicio de certificación documental que utiliza la blockchain de **Stellar** (pubnet) para registrar la existencia de un documento en un momento concreto del tiempo, sin revelar su contenido.

### Flujo de funcionamiento

1. El usuario envía un fichero (texto, PDF, imagen, cualquier formato).
2. El sistema calcula su **hash SHA-256** (huella digital única de 64 caracteres hexadecimales).
3. Ese hash se escribe en la blockchain de Stellar mediante una operación `manage_data`.
4. El sistema devuelve un comprobante con el hash de la transacción, el ledger donde quedó grabado y enlaces de verificación pública.

### ¿Por qué blockchain?

Una vez escrita, la operación es **inmutable**. Nadie —ni el operador de la plataforma— puede modificarla o borrarla. Cualquier persona con el hash del documento puede verificar por sí misma que el registro existe, sin depender de terceros.

### Cumplimiento LGPD/RGPD

- Solo el hash SHA-256 se almacena en la blockchain (dato seudónimo, irreversible).
- El contenido del documento **nunca** se almacena en el servidor (solo se procesa efímeramente).
- Todas las operaciones quedan registradas en `tblAccion` y en la carpeta `ACTIONS/` para auditoría.
- Los datos personales (email) se almacenan con propósito legítimo de autenticación.

---

## 2. Conceptos básicos de Stellar

### 2.1 Hash SHA-256

Un hash es el resultado de pasar datos por una función matemática que produce una cadena de 64 caracteres hexadecimales. Dos documentos idénticos producen el mismo hash; dos documentos distintos producen hashes distintos. El hash **no revela** el contenido original ni permite reconstruirlo.

```bash
# Generar un hash en Linux / macOS / WSL
echo -n "microwd online stellar" | sha256sum
```

### 2.2 Operación manage_data

En Stellar, una cuenta puede almacenar pares clave-valor en su ledger. La clave es el hash SHA-256 del documento; el valor es la fecha/hora UTC del registro. Estas entradas son **inmutables**.

### 2.3 Cuentas Stellar

La plataforma mantiene 3 cuentas Stellar en **pubnet** (red principal). Por cada documento nuevo se selecciona una cuenta en round-robin con failover automático (mínimo 5 XLM de reserva por cuenta).

### 2.4 Red pública vs Testnet

- **Pubnet**: red principal de Stellar. Las transacciones son reales y permanentes.
- **Testnet**: red de pruebas. No se usa en esta plataforma.

---

## 3. Roles del sistema

| Rol | Autenticación | Permisos |
|-----|--------------|----------|
| **Administrador** | X-API-Key, o email + contraseña (Basic Auth) | Todos: registro, verificación, gestión de usuarios, consultas. Acceso al panel admin. |
| **Supervisor** | HTTP Basic Auth (email + contraseña) | Registro, verificación, consulta de estado. Recibe notificaciones por email. |
| **Técnico** | Email + PIN de 6 dígitos, o código de 12 caracteres | Registro (con verificación por email), verificación |

Un mismo usuario puede tener **varios roles** a la vez (ej: técnico + supervisor, o admin + técnico). En ese caso, puede autenticarse por cualquiera de los métodos y recibe las ventajas de cada perfil.

### 3.1 Código de técnico

Al crear un técnico, el sistema genera:
- **Código de autorización** de 12 caracteres (alfanumérico, mayúsculas) para usar en la API (`codigo_tecnico`).
- **PIN de 6 dígitos** para autenticación en formularios web (registrar.php, verificar.php).

Estos valores se muestran **una sola vez** al crear el usuario. El PIN se almacena con hash bcrypt y no se puede recuperar.

---

## 4. Registrar un documento

### 4.1 Desde la web (técnico)

1. Accede a [registrar.php](https://www.microwd.online/registrar.php).
2. Introduce tu **email de técnico** y tu **PIN de 6 dígitos**.
3. Selecciona la pestaña **Subir fichero** o **Pegar texto**.
4. Arrastra el fichero o pega el contenido.
5. (Opcional) Introduce el **email del destinatario** para que reciba notificación.
6. Introduce un **PIN de verificación de 6 dígitos** que se enviará al destinatario.
7. Haz clic en **Registrar en Stellar**.
8. **Importante**: recibirás un email de confirmación. El registro **no se ejecuta** hasta que hagas clic en el enlace de verificación.

### 4.2 Desde la línea de comandos (admin/supervisor)

```bash
# Con X-API-Key (admin)
curl -X POST https://www.microwd.online/api/register.php \
  -H "X-API-Key: TU_CLAVE_API" \
  -F "file=@documento.txt" \
  -F "pin=123456"

# Con Basic Auth (supervisor)
curl -X POST https://www.microwd.online/api/register.php \
  -u "supervisor@email.com:contraseña" \
  -F "file=@documento.txt" \
  -F "pin=123456"

# Con email_destinatario (opcional)
curl -X POST https://www.microwd.online/api/register.php \
  -H "X-API-Key: TU_CLAVE_API" \
  -F "file=@documento.txt" \
  -F "pin=123456" \
  -F "email_destinatario=destinatario@example.com"
```

### 4.3 Idempotencia

Registrar el mismo documento dos veces **no crea una segunda transacción**. El sistema detecta el hash duplicado y devuelve la información de la transacción original con `"already_registered": true`.

### 4.4 Formato de respuesta exitosa

```json
{
  "success": true,
  "hash": "3c2e8f5a...",
  "tx_hash": "a1b2c3d4...",
  "ledger": 51234567,
  "source_account": "GATEKT3J...",
  "created_at": "2026-06-21 10:30:00 UTC",
  "network": "pubnet",
  "content_length": 1234,
  "filename": "documento.txt",
  "verify_tx_url": "https://stellar.expert/explorer/public/tx/a1b2c3d4...",
  "verify_data_url": "https://horizon.stellar.org/accounts/GATEKT3J.../data/3c2e8f5a..."
}
```

---

## 5. Verificar un documento

### 5.1 Desde la web (técnico)

1. Accede a [verificar.php](https://www.microwd.online/verificar.php).
2. Introduce tu **email de técnico** y tu **PIN de 6 dígitos**.
3. Elige el método:
   - **Subir fichero**: arrastra el documento.
   - **Pegar texto**: pega el contenido.
   - **Hash directo**: escribe el hash SHA-256 (64 caracteres hex).
4. Haz clic en **Verificar**.

### 5.2 Por fichero (API)

```bash
curl -X POST https://www.microwd.online/api/verify.php \
  -H "X-API-Key: TU_CLAVE_API" \
  -F "file=@documento_sospechoso.pdf"
```

### 5.3 Por hash (API)

```bash
curl "https://www.microwd.online/api/verify.php?hash=3c2e8f5a..." \
  -H "X-API-Key: TU_CLAVE_API"
```

### 5.4 Verificación pública (sin credenciales)

Cualquier persona con el hash puede verificar directamente en la blockchain:

```
https://horizon.stellar.org/accounts/GATEKT3J.../data/3c2e8f5a...
```

---

## 6. Autenticación en la API

La API acepta **tres métodos de autenticación**:

| Método | Transmisión | Perfil | Endpoints |
|--------|------------|--------|-----------|
| **X-API-Key** | Header `X-API-Key: <clave>` | Administrador | Todos |
| **Basic Auth** | Header `Authorization: Basic <base64>` | Supervisor activo | register, verify |
| **Código técnico** | POST body `codigo_tecnico=<código>` | Técnico activo | register |
| **Email + PIN** | POST body `tecnico_email` + `tecnico_pin` | Técnico activo | register, verify (web) |

### Rate limiting

| Contexto | Límite | Alcance |
|----------|--------|---------|
| Admin (API key) | 50 req/min | Por API key |
| Usuario (Basic Auth) | 10 req/min | Por usuario |
| Técnico (email+PIN) | 10 req/min | Por técnico |
| Status público | 30 req/min | Por IP |
| Verify by email (público) | 5 req/min | Por IP |
| Verify by email (mismo email) | 3 req/min | Por email |
| Confirm registration | 10 req/min | Por IP |
| Alta de usuarios | 5 req/min | Por IP |

Si se excede, la API responde `429 Too Many Requests` con header `Retry-After`.

---

## 7. Gestión de usuarios

### 7.1 Alta de usuarios

Cualquier persona con la **X-API-Key de administrador** puede crear usuarios en [alta-usuarios.php](https://www.microwd.online/alta-usuarios.php).

**Requisitos:**
- Email válido.
- Contraseña de al menos 8 caracteres.
- Selección de roles mediante checkboxes: **Técnico**, **Supervisor**, o ambos.
- X-API-Key de administrador.

**Resultado:**
- Usuario creado **inactivo** por defecto.
- Si tiene el rol técnico: se muestra código de 12 caracteres + PIN de 6 dígitos (guardar de forma segura, no se recupera).
- Si tiene ambos roles: recibe código + PIN de técnico Y puede usar Basic Auth como supervisor.
- Un administrador debe activar al usuario antes de que pueda operar.

### 7.2 Activación / desactivación / borrado

Desde [admin.php](https://www.microwd.online/admin.php) (requiere X-API-Key):

- **Activar**: permite al usuario autenticarse.
- **Desactivar**: bloquea el acceso sin borrar los datos.
- **Borrar**: elimina al usuario de la base de datos.

API equivalente:

```bash
# Activar usuario
curl -X POST "https://www.microwd.online/api/admin/users.php?mode=toggle_active&user_id=5&activo=1" \
  -H "X-API-Key: TU_CLAVE_API"
```

### 7.3 Regenerar código de técnico

Si un técnico pierde su código, un administrador puede regenerarlo:

```bash
curl -X POST "https://www.microwd.online/api/admin/users.php?mode=regenerate_code&user_id=5" \
  -H "X-API-Key: TU_CLAVE_API"
```

### 7.4 Seguridad de contraseñas

- Almacenadas con **bcrypt** (coste 10).
- Comparación con `hash_equals()` (protección contra timing attacks).
- El hash nunca se devuelve en respuestas JSON.
- Los PIN de técnico también se almacenan con bcrypt.

---

## 8. Panel de administración

Accede en [admin.php](https://www.microwd.online/admin.php) con la X-API-Key de administrador.

### 8.1 Pestaña Operaciones

Lista filtrable de todas las acciones registradas. Filtros disponibles:
- **Acción**: register_submitted, verify_hash, register_error, etc.
- **Aceptado**: sí/no.
- **Hash** SHA-256 o **Transaction Hash** de Stellar.
- **Cuenta origen** (G…).
- **Rango de fechas**.
- **Orden**: ASC / DESC.

### 8.2 Pestaña Usuarios

Lista de usuarios con filtro por email y estado (activo/inactivo). Acciones:
- Activar / Desactivar / Borrar.
- Regenerar código de técnico.

---

## 9. Uso programático de la API

### 9.1 Endpoints

| Método | Ruta | Auth | Descripción |
|--------|------|------|-------------|
| POST | `/api/register.php` | Admin / Supervisor / Técnico | Registrar documento (admin/supervisor: directo; técnico: 2 pasos) |
| POST | `/api/verify.php` | Admin / Supervisor / Técnico | Verificar por contenido |
| GET | `/api/verify.php?hash=` | Admin / Supervisor / Técnico | Verificar por hash |
| GET | `/api/verify-by-email.php?email=` | Público | Listar operaciones asociadas a un email (sin PIN) |
| POST | `/api/verify-by-email.php` | Público (email + PIN) | Verificar documento con PIN de destinatario |
| GET | `/api/status.php` | Público | Salud, balances, actividad |
| GET | `/api/health.php` | Público | Health check para monitorización |
| GET | `/api/history.php` | Admin | Últimos registros (hashes + tx) |
| GET | `/api/confirm-registration.php?token=` | Público (token) | Confirmar registro pendiente y ejecutar transacción Stellar |
| GET | `/api/admin/operations.php` | Admin | Consulta de operaciones con filtros |
| GET | `/api/admin/logs.php` | Admin | Consulta de auditoría (tblAccion) con filtros |
| GET/POST | `/api/admin/users.php` | Admin | Gestión de usuarios (listar, crear, toggle, borrar, regenerar código) |
| GET | `/api/index.php` | Público | Info del servicio |

### 9.2 Ejemplo: JavaScript (fetch)

```javascript
const API_KEY = 'tu-clave-admin';

async function registrar(file) {
  const form = new FormData();
  form.append('file', file);

  const res = await fetch('https://www.microwd.online/api/register.php', {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY },
    body: form
  });
  return res.json();
}
```

### 9.3 Ejemplo: Python

```python
import requests
import hashlib

def verificar_archivo(path, api_key):
    with open(path, 'rb') as f:
        content = f.read()
    h = hashlib.sha256(content).hexdigest()

    resp = requests.get(
        'https://www.microwd.online/api/verify.php',
        params={'hash': h},
        headers={'X-API-Key': api_key},
    )
    return resp.json()
```

### 9.4 Formato de respuesta

Todas las respuestas incluyen:

```json
{
  "success": true | false,
  "error": "mensaje si success=false",
  "code": "código de error"
}
```

### 9.5 Códigos de error

| Código | Significado |
|--------|-------------|
| `unauthorized` | Credenciales ausentes o inválidas |
| `forbidden` | Sin permisos para el endpoint |
| `rate_limited` | Límite de peticiones excedido |
| `invalid_file` | Fichero vacío o no legible |
| `stellar_error` | Error al enviar transacción a Stellar |
| `db_error` | Error de base de datos |
| `duplicate_hash` | El documento ya fue registrado |
| `user_inactive` | Usuario existe pero no está activo |

---

## 10. Monitorización y estado

### 10.1 Panel de estado público

[estado.php](https://www.microwd.online/estado.php) muestra (sin autenticación):
- Salud de Horizon (API de Stellar).
- Balances XLM de las 3 cuentas.
- Número de secuencia y entradas de datos.
- Actividad: total y últimas 24h de registros, verificaciones y errores.

### 10.2 Health check

```
GET https://www.microwd.online/api/health.php
→ {"ok":true,"service":"microwd.online","ts":"2026-06-21T10:00:00Z"}
```

Compatible con UptimeRobot, Better Uptime, Healthchecks.io.

### 10.3 Monitor de saldos

Script programado (`balance_monitor.ps1`) que se ejecuta diariamente a las 08:00. Si alguna cuenta baja de 10 XLM, escribe alerta en `ACTIONS/MONITOR/`.

### 10.4 Log de errores PHP

Los errores de PHP se escriben en `php_errors.log` en la raíz del sitio. La configuración está en `.user.ini`:

```ini
log_errors = On
display_errors = Off
error_reporting = E_ALL & ~E_DEPRECATED & ~E_NOTICE
error_log = C:\inetpub\wwwroot\MICROWD.ONLINE\php_errors.log
```

- Los errores **no** se muestran al usuario (por seguridad).
- El archivo se crea automáticamente al producirse el primer error.
- Revisar este log periódicamente para detectar problemas.

---

## 11. Seguridad

### 11.1 Protección anti-bots

El módulo `api/bot_protection.php` implementa un sistema de strikes y baneo progresivo por IP.

**Detección — qué dispara un strike:**

| Evento | Reason | Dónde |
|--------|--------|-------|
| Autenticación fallida (API key, Basic Auth, PIN) | `auth_failed` | `api/auth.php` |
| User-Agent de escáner conocido (curl, nikto, sqlmap, nmap, etc.) | `bad_ua` | `bot_check()` en cada página |
| Petición a paths prohibidos (/.env, /.git, /wp-admin, etc.) | `probe` | `bot_check()` en cada página |
| Código de alta incorrecto | `alta_failed` | `alta-usuarios.php` |

**Escalación progresiva:**

| Strikes acumulados | Consecuencia |
|--------------------|-------------|
| 0–2 | Sin bloqueo. Delay de 0.5 s por strike acumulado (máx 3 s). |
| 3 | Baneo 5 minutos |
| 6 | Baneo 30 minutos |
| 9 | Baneo 1 hora |
| 12 | Baneo 24 horas |

- Los strikes no expiran hasta 24 h después de la última incidencia.
- Al expirar un baneo, la IP vuelve a nivel de strikes (no se borran, solo se demote).
- El archivo `.ban_list` se limpia automáticamente cada 50 operaciones.
- **Control de concurrencia**: todas las lecturas/escrituras de `.ban_list` usan `flock()` para evitar condiciones de carrera entre requests simultáneos.

**Otras protecciones:**
- **Rate limiting** por IP y por credencial (ver sección 6).
- **Honeypot + dropdown anti-spam** en formularios (`includes/spam_protection.php`).
- **Protección CSRF** con token de sesión en formularios POST (`alta-usuarios.php`, `email-test.php`).
- **Limpieza automática de registros pendientes**: los archivos en `PENDING/` con más de 24 h se eliminan automáticamente (~1 de cada 25 requests a register.php).

### 11.2 Protección de archivos sensibles

`web.config` raíz oculta del acceso HTTP mediante `hiddenSegments`:
- `.env`, `.git`, `.claude`, `.claudeignore`, `.htaccess`
- `.ban_list`, `.ban_list.lock`, `.rate_limit`, `.api_key`, `.register.log`
- `.alta_codigo`, `.account_index`, `.health_cache`
- `PENDING/`, `BACKUP/`, `ACTIONS/`, `DOCs/STELLAR/`, `vendor/`, `tests/`, `includes/`, `logs/`

Extensiones bloqueadas para descarga directa: `.env`, `.ps1`, `.sql`, `.md`, `.json`, `.xml`

`api/web.config` añade protección adicional para el directorio `api/`:
- `.account_index`, `.health_cache`

### 11.3 Limpieza automática de PENDING

Los registros iniciados por técnicos que no se confirman en 24 horas se eliminan automáticamente. La limpieza se activa de forma probabilística (~1 de cada 25 peticiones a `register.php`) para no añadir sobrecarga. Los archivos eliminados son los pares `.json` + `.dat` dentro de `PENDING/`.

### 11.4 Flujo de verificación en dos pasos

Para técnicos, el registro requiere confirmación por email. Esto previene que credenciales capturadas puedan realizar registros no autorizados sin acceso al email del técnico.

---

## 12. Backup y recuperación

### 12.1 Backup diario

Un script programado (`backup.ps1`) se ejecuta cada día a las 07:00:
1. Vuelca la base de datos `db_microwd` en `BACKUP/`.
2. Comprime toda la carpeta `MICROWD.ONLINE` en un `.rar` en la carpeta de descargas.

### 12.2 Auditoría

- Todas las operaciones quedan registradas en `ACTIONS/` (archivos `.log` individuales).
- Tabla `tblAccion` en base de datos con historial completo.
- `tblUsuario` registra IP y fecha de último login.

### 12.3 Backup de Obsidian

Script `OBSIDIAN_Backup.ps1` en `C:\inetpub\wwwroot\OBSIDIAN\` para backup de las vaults.

---

## 13. Preguntas frecuentes

### ¿Puedo registrar cualquier tipo de archivo?

Sí. El sistema procesa bytes; no importa si es .txt, .pdf, .jpg o un binario. Límite: **10 MB** por petición.

### ¿El documento se almacena en la blockchain?

**No.** Solo se guarda el hash SHA-256 (64 caracteres). El documento original nunca sale de tu poder.

### ¿Cuánto cuesta cada registro?

Cada operación `manage_data` consume ≈0.00001 XLM en fees de red. Las cuentas de la plataforma cubren este coste. No se cobra a los usuarios.

### ¿Cuánto tarda en confirmarse?

Stellar pubnet confirma en **3-5 segundos**. La respuesta incluye el ledger donde quedó grabada la operación.

### ¿Qué pasa si la blockchain de Stellar desaparece?

Stellar es una red descentralizada con cientos de validadores. Si desapareciera, los hashes quedan en los backups diarios de `tblAccion`, exportables desde el panel de administración.

### ¿Es válido legalmente?

La validez legal depende de la jurisdicción. El servicio proporciona **evidencia técnica** (hash + timestamp + transacción inmutable). Consulta con un abogado para tu caso concreto.

### ¿Puedo verificar sin la API?

Sí. Cualquier persona con el hash SHA-256 puede consultar la blockchain en [stellar.expert](https://stellar.expert) o [Horizon](https://horizon.stellar.org). No necesita credenciales.

### ¿Cómo verifico un documento sin ser usuario?

Usa la página [verificar.php](https://www.microwd.online/verificar.php) con las credenciales de un técnico, o consulta directamente en Horizon con el hash.

### ¿Qué hago si pierdo mi PIN de técnico?

El PIN no se puede recuperar (se almacena con hash). Contacta con un administrador para que te cree un nuevo usuario técnico.

### ¿Qué es el email de confirmación?

Cuando un técnico registra un documento desde la web, recibe un email con un enlace. El registro en Stellar **no se ejecuta** hasta que el técnico hace clic en ese enlace. Es una medida de seguridad adicional.

---

## Metadatos del documento

- **Versión**: 1.2
- **Fecha**: 2026-06-22
- **Cambios en v1.2**: soporte de roles múltiples (admin, técnico, supervisor) con SET en MySQL; añadido rol 'admin' con autenticación por email+contraseña (Basic Auth); login dual (X-API-Key o email+pass) en panel admin; corregida tabla de rate limiting; añadido parámetro PIN en ejemplos de register; ampliada documentación anti-bot; añadidos endpoints verify-by-email, admin/logs; actualizada lista de hiddenSegments
- **Cambios en v1.1**: añadida sección de logging de errores PHP; corregida lista de directorios protegidos en web.config
- **Formato**: Markdown
- **Visor recomendado**: [Markdown View by tinyGOODIES](https://www.microsoft.com/store/productId/9N5T3R9QXH7W) (gratuito, Microsoft Store)

---

*Este documento debe actualizarse cada vez que haya un cambio en la plataforma que afecte a su uso o funcionamiento.*