Files
localesp/openspec/changes/hide-admin-route/tasks.md
T
edgar.friendly 695d59d31e
deploy-branch / deploy (push) Successful in 3m18s
deploy-branch / teardown (push) Skipped
tests / Unitarias + componente + build (push) Failing after 3m15s
tests / Integración (Nominatim real, opt-in) (push) Skipped
tests / Unitarias + componente + build (pull_request) Failing after 3m25s
tests / Integración (Nominatim real, opt-in) (pull_request) Skipped
ci(deploy): config por entorno en el repo (scripts/entornos.env)
La config de prefijo admin pasa del host (/etc/localesp/<slug>.env) al
repo, para que viaje con el código que despliega y se revise en PRs:

- scripts/entornos.env: mapping <slug>=<prefijo> (prototipo-yb01=
  /administrador; master y prototipo-yb01-ef como plantilla comentada)
- env.sh: servicio Config::admin_prefix lee el mapping; require_config
  falla con mensaje claro si la rama no tiene entrada; Env::deploy
  regenera <dest>/.env desde el repo (el servidor lo autocarga)
- deploy.yml: el build exporta el prefijo del mapping antes de compilar
2026-10-03 14:56:08 +02:00

137 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Tasks: Hide Admin Route
> **Pivote decidido por el usuario (2026-10-02):** "solo quiero que se pueda
> configurar el prefijo de admin, nada más". El enfoque de middleware de
> enmascaramiento con 404 se **descarta**; las rutas admin se montan bajo un
> **prefijo configurable** (`LOCALESP_ADMIN_PREFIX`, única variable para
> servidor y frontend) y las rutas históricas bajo
> `/api` dejan de existir (404 natural, sin handler). `reportar`/`confirmar`
> siguen públicas (las usa la web); `DELETE /api/locales/:id` pasa al prefijo.
>
> **Estado (2026-10-02, tras el pivote + obligatoriedad):** implementado y
> verificado. `./node_modules/.bin/vitest run` → **109/109 en verde** (16
> ficheros), incluyendo `tests/unit/test-routes.spec.js` (18 tests, prefijo
> configurado) y `tests/unit/test-admin-prefix-required.spec.js` (fail-fast
> sin configurar).
> **Actualización 2 (2026-10-02):** a petición del usuario, `LOCALESP_ADMIN_PREFIX`
> pasa a ser obligatoria (sin default `/api`): sin ella el servidor lanza error
> claro y no arranca. Añadidos `.env.example`, cargador de `.env` en el servidor
> (no sobrescribe el entorno) y lectura del prefijo en `vite.config.js` vía
> `loadEnv`. Test de compatibilidad con `/api` sustituido por
> `test-admin-prefix-required.spec.js` (fail-fast verificado). Suite: 109/109.
>
> **Actualización 3 (2026-10-02):** eliminada la redundancia `VITE_ADMIN_PREFIX`:
> **una sola variable** (`LOCALESP_ADMIN_PREFIX`) para servidor, proxy de dev
> y frontend (Vite la expone vía `envPrefix`; `npm run build` falla si falta).
>
> **Actualización 4 (2026-10-03):** el panel admin vive en la raíz del prefijo
> (`/administrador` en prototipo-yb01) y `/admin` muestra la web pública.
>
> **Actualización 5 (2026-10-03):** config por entorno movida del host al repo
> (`scripts/entornos.env`, mapping `slug=prefijo`): el workflow la aplica al
> build y `deploy.sh` genera `<dest>/.env` desde ella. Fail-fast sin entrada.
## 1. Revisión de rutas existentes
- [x] 1.1 Leer y entender la estructura de rutas de `server/index.js`
- [x] 1.2 Identificar las rutas solo-admin (`/api/pendientes`, `/api/reportes`, `/api/locales/:id/reportar`, `/api/locales/:id/confirmar`, `/api/locales/:id`, `/api/aprobar/:id`, `/api/rechazar/:id`, `/api/reportes/:id/descartar`)
- [x] 1.3 Documentar el orden de rutas y la posición del fallback SPA
## 2. Prefijo de administración configurable (re-encaminado)
> Originalmente "middleware de ofuscación"; sustituido por el pivote al
> prefijo configurable. El middleware roto y `ADMIN_ROUTES`/`ROUTE_REGEXPS`
> se eliminaron del servidor.
- [x] 2.1 Montar las rutas admin bajo `ADMIN_PREFIX` (`LOCALESP_ADMIN_PREFIX`, **obligatoria y sin valor por defecto**: fail-fast al arrancar si falta; template en `.env.example`, que el servidor autocarga sin pisar el entorno)
- [x] 2.2 Rutas bajo prefijo: `pendientes`, `aprobar/:id`, `rechazar/:id`, `locales/:id` (DELETE), `reportes`, `reportes/:id/descartar` — sin middleware ni matching por patrón
- [x] 2.3 Posición: mismas posiciones que las rutas originales; el fallback SPA sigue excluyendo `api/`
- [x] 2.4 Verificado por tests: las rutas históricas bajo `/api` devuelven 404 cuando el prefijo está configurado
## 3. Verificar que las rutas no-admin siguen funcionando
- [x] 3.1 `GET /api/locales` → 200 con lista de locales (test)
- [x] 3.2 `POST /api/propuestas` → 201 con la propuesta creada (test)
- [x] 3.3 Fallback SPA `GET /` sirve `index.html` (test, aserción case-insensitive)
## 4. Documentación
- [x] 4.1 Documentar las reglas de protección y las rutas afectadas en el spec (`specs/route-obfuscation/spec.md`, actualizado al enfoque de prefijo)
- [x] 4.2 README actualizado: tabla de rutas admin bajo prefijo, variable única `LOCALESP_ADMIN_PREFIX` (servidor + proxy dev + build), proxy de dev y advertencia de que es ocultación, no autenticación
- [x] 4.3 `DELETE /api/locales/:id` — decidido por el usuario: pasa al prefijo configurable (test cubre borrado bajo prefijo y 404 en la ruta antigua)
## 5. Pruebas
> Con el enfoque de prefijo, "protegida" = la ruta histórica bajo `/api` ya no
> tiene handler (404 idéntico para cualquier método, query, extensión o
> variante de cadena) y la funcionalidad vive bajo `$ADMIN_PREFIX`.
> Cubierto por `tests/unit/test-routes.spec.js` (prefijo `/prefijo-admin-test`)
> y `tests/unit/test-admin-prefix-default.spec.js` (prefijo por defecto).
### 5.1 Rutas públicas (deben funcionar sin cambios)
- [x] 5.1 `GET /api/locales` → 200 (test)
- [x] 5.2 `POST /api/propuestas` → 201 con cuerpo (test)
- [x] 5.3 `POST /api/check-duplicado` → 200 con contrato `coincidencias` intacto (test)
- [x] 5.4 N/A: no existe ruta `/health` ni middleware que la intercepte
- [x] 5.5 `GET /` → 200 sirve `dist/index.html` (test, doctype case-insensitive)
- [x] 5.6 N/A: assets estáticos los sirve `express.static` sin intervención
- [x] 5.7 N/A: ídem
- [x] 5.8 Corregido el enunciado: `GET /api/locales/123` → 404 (el fallback SPA siempre excluyó `api/`); sin fuga
- [x] 5.9 `GET /api/config/filtro_palabras` → 200 (test)
### 5.2 Rutas protegidas (la ruta histórica devuelve 404; la función vive bajo prefijo)
- [x] 5.10 `GET /api/pendientes` → 404 y `$P/pendientes` → 200 con datos (test)
- [x] 5.11 `GET /api/reportes` → 404 y `$P/reportes` → 200 con datos (test)
- [x] 5.12 `POST /api/locales/:id/reportar` → **pública** (la usa la web); su flujo admin (listar/descartar reportes) bajo prefijo (test)
- [x] 5.13 `POST /api/locales/:id/confirmar` → **pública** (la usa la web); 200 renueva fecha (test)
- [x] 5.14 `POST /api/aprobar/:id` → 404 en `/api`; bajo prefijo mueve a locales y saca de pendientes (test)
- [x] 5.15 `POST /api/rechazar/:id` → 404 en `/api`; bajo prefido elimina pendiente (test)
- [x] 5.16 `POST /api/reportes/:id/descartar` → 404 en `/api`; bajo prefijo descarta (test)
### 5.3 Comportamiento (evitar falsos positivos)
- [x] 5.17 `GET /api/locales` → 200 (test)
- [x] 5.18/5.19/5.20 Corregido el enunciado: cualquier GET bajo `api/` sin handler → 404 (el fallback SPA siempre excluyó `api/`); sin middleware que bloquee de más
- [x] 5.21 `GET /API/PENDIENTES` → sin handler API; cae al fallback SPA sin datos (test)
- [x] 5.22 `GET /api/pendientes/extra` → 404 (test)
- [x] 5.23 `POST /api/locales/:id/reponer` → 404 (sin handler)
### 5.4 Pruebas de seguridad (enumeración y rutas maliciosas)
- [x] 5.24 `GET /api/pendientes.json` → 404 (test)
- [x] 5.25 `GET /api/pending` / `/api/xpendientes` → 404 (test)
- [x] 5.26–5.34 Sin handler bajo `/api`, cualquier método/query/extensión/cadena recibe el mismo 404 (por construcción); las variantes que no empiezan por `api/` reciben el HTML genérico del fallback SPA, sin datos
- [x] 5.35 `GET /api/xpendientes` → 404 (test)
### 5.5 Pruebas de regresión y no-regresión
- [x] 5.36 `POST /api/propuestas` → 201 con campos correctos (test); payload malformado gestionado por la BD/validación existente (sin cambios en este cambio)
- [x] 5.38 `DELETE` bajo prefijo → 200 y borra local + reportes (test); ruta antigua → 404
- [x] 5.39–5.44 N/A o por construcción: no hay middleware, no hay cabeceras especiales ni logs nuevos
- [x] Suite completa previa (componentes incluidos) en verde: 110/110
### 5.6 Validación contra el esquema de base de datos
- [x] 5.45 `GET /api/locales` sin cambios de columnas (no se tocó la query)
- [x] 5.46 `POST /api/propuestas` sin cambios (ídem)
- [x] 5.47 `$P/reportes` devuelve exactamente lo que devolvía `/api/reportes` (misma query)
## 6. Limpieza
- [x] 6.1 N/A tras el pivote: no hay lista `ADMIN_ROUTES`
- [x] 6.2 `DELETE /api/locales/:id` resuelto: vive bajo el prefijo (4.3)
- [x] 6.3 N/A tras el pivote: `reportes/:id/descartar` montado bajo prefijo y verificado por test
- [x] 6.4 Ficheros de prueba duplicados/muertos eliminados: `tests/integration/test-hide-admin-route.js` (nunca recogido por ningún include y con sintaxis rota) y `vitest.config.js` redundante (pisaba `vitest.config.mjs`, que es la config vigente); se conserva un único `tests/unit/test-routes.spec.js` (+ el de prefijo obligatorio)
## 7. Seguimiento: protección fina por método
> Obsoleto tras el pivote: el prefijo configurable ya separa superficie
> pública y admin sin matching por método. Si en el futuro se añade
> autenticación real, este apartado queda como referencia.
## 8. Bloqueadores para cerrar el cambio
- [x] 8.1 Obsoleto: el middleware se eliminó (pivote al prefijo)
- [x] 8.2 El handler de `GET pendientes` existe de nuevo, montado bajo el prefijo: quien conoce la URL prefijada obtiene los datos; la ruta `/api/pendientes` histórica devuelve 404
- [x] 8.3 Suite en verde: 109/109 tests (19 de rutas/prefijo en 2 ficheros: configurado + obligatorio)
- [x] 8.4 Aserción del SPA corregida (comparación case-insensitive de `<!doctype html>`)
- [x] 8.5 Revertidos los cambios fuera de alcance: `distanciaMetros` (haversine) restaurada, `db`→`Db` deshecho, comentarios originales restaurados, contrato `coincidencias` intacto, `src/App.jsx` (resaltado `?local=ID` + bloque de estadísticas) restaurado vía `git checkout`, `vite.config.js` limpio (solo proxy + prefijo de dev), `package-lock.json` revertido
- [x] 8.6 README actualizado (4.2) y `DELETE /api/locales/:id` decidido (4.3)