DeviceReg

Proyecto de registro de dispositivos cliente-servidor. Combina dos componentes:

1. Servidor de registro (PHP + MariaDB): recibe check-ins de equipos Windows y mantiene un histórico de conexiones por dispositivo.
2. Servidor de tokens local (Go): utilidad auxiliar que expone un token de autenticación basado en la identidad del sistema, útil para pruebas locales entre capas.

---

Arquitectura general

Cliente Windows (PowerShell)
        │  POST /api/v1/device-checkin  (JSON)
        ▼
Servidor PHP (servidor/)
        │  PDO/mysqli → MariaDB
        ▼
  devices  ◄── device_checkins

El servidor Go (/token) es independiente y no participa del flujo de registro; sirve como herramienta de apoyo para validación y pruebas locales.

---

1. Servidor de registro (PHP + MariaDB)

Requisitos

• PHP 7.4+
• MariaDB 10.3+
• Extensión mysqli

Estructura

servidor/
├── config.php      # Credenciales de BD y settings (api base_url, api_key)
├── database.php    # Singleton Database (mysqli) + DeviceManager (lógica)
├── router.php      # Clase Router: handleCheckIn / handleDeviceHistory
├── index.php       # Front controller: enruta URLs y responde JSON
└── schema.sql      # Esquema MariaDB (BD device_registration)

Base de datos

El script servidor/schema.sql crea la base device_registration con:

• devices(id, device_id VARCHAR UNIQUE, mac, hostname, created_at)
• device_checkins(id, device_id VARCHAR FK, username, timestamp, ip_address)

Usuario configurado en config.php: devicereg_user.

Endpoints

Base URL definida en config.php → /api/v1/.

POST /api/v1/device-checkin

Payload (JSON):

{
  "device_id": "UUID",
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "hostname": "WORKSTATION-1",
  "username": "john.doe"
}

• Campo user también es aceptado (se normaliza a username).
• Valida campos requeridos y retorna 400 si faltan.
• Inserta/obtiene el dispositivo (upsert) y registra el check-in con IP de origen.
• Respuesta 201:

{
  "id": 12,
  "status": "created | verified",
  "device_id": 5,
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "hostname": "WORKSTATION-1",
  "username": "john.doe",
  "ip_address": "127.0.0.1"
}

GET /api/v1/device/{device_id}/history

Respuesta paginada (page, per_page por query string):

{
  "id": 5,
  "mac_address": "AA:BB:CC:DD:EE:FF",
  "hostname": "WORKSTATION-1",
  "checkins": [
    { "id": 12, "username": "john.doe", "created_at": "2026-07-19 21:00:00" }
  ],
  "page": 1,
  "per_page": 10
}

Seguridad

• config.php incluye security.api_key. Si se define, el front controller exige el header X-api-key (retorna 401 si no coincide).
• Se registra la IP de origen en cada check-in para auditoría.

Ejecución local

cd servidor
php -S localhost:8080 -t .

Luego probá con scripts/test_api.sh, scripts/run_tests.sh o docs/curl_examples.md.

---

2. Servidor de tokens local (Go) — LEGACY

Componente histórico, ya no forma parte del flujo de registro de equipos. El código fuente está en la carpeta legacy/.

Servidor HTTP minimalista que expone un token derivado de la identidad del sistema (UUID + MAC).

Características

• Endpoint GET /token en http://localhost:8085
• Retorna JSON: token, hostname, status
• CORS abierto (Access-Control-Allow-Origin: *), maneja preflight OPTIONS
• Token generado con SHA-256 sobre UUID + MAC + clave secreta, cifrado AES-256 (CTR) y guardado en config.dat

Compilar y ejecutar

cd legacy
go build -o devicereg .
./devicereg

Respuesta de ejemplo:

{
  "token": "abc123...",
  "hostname": "ozba-machine",
  "status": "ok"
}

---

Cliente Windows (PowerShell)

client/device-client.ps1 recolecta UUID, MAC, hostname y usuario actual, los cachea en %PROGRAMDATA%\DeviceMonitor\state.json (renovación cada 14 días) y envía un POST al servidor en el login mediante una tarea programada. La URL se configura en config.ini:

[Server]
URL = https://localhost/api/v1/device-checkin

Consultá cliente.md y idea.md para el detalle de la planificación.

---

Documentación del proyecto

• idea.md — visión general cliente/servidor
• roadmap.md — fases de desarrollo
• servidor.md / db.md — especificación de API y esquema
• cliente.md / backlog.md — detalle de cliente y pendientes

Futuras mejoras

• Validación de tokens en el servidor Go
• Configuración dinámica de puerto/origen CORS
• Compresión de caché del cliente y rotación de bitácora
• Documentar variables de entorno para producción