Files
localesp/openspec/changes/hide-admin-route/specs/route-obfuscation/spec.md
T
edgar.friendly 85a054d886
deploy-branch / deploy (push) Failing after 3m7s
deploy-branch / teardown (push) Skipped
tests / Unitarias + componente + build (push) Failing after 3m17s
tests / Integración (Nominatim real, opt-in) (push) Skipped
tests / Unitarias + componente + build (pull_request) Failing after 3m10s
tests / Integración (Nominatim real, opt-in) (pull_request) Skipped
feat(seguridad): rutas admin bajo prefijo configurable obligatorio
Cambio openspec hide-admin-route: las rutas de administración se montan
bajo LOCALESP_ADMIN_PREFIX (única variable, obligatoria, sin valor por
defecto) y las rutas históricas /api/... dejan de existir (404 natural).

- server: autocarga de .env (sin pisar el entorno) y fail-fast claro si
  falta LOCALESP_ADMIN_PREFIX; reportar/confirmar siguen públicas
- frontend: src/api.js usa el prefijo expuesto por Vite (envPrefix);
  npm run build falla sin la variable; proxy de dev la lee vía loadEnv
- .env.example como template único de configuración
- tests: 109/109 en verde (rutas bajo prefijo, 404s históricos y
  fail-fast sin configurar)
- openspec: artefactos del cambio sincronizados (design/spec/tasks)
2026-10-02 21:57:02 +02:00

3.8 KiB

Route Obfuscation Spec

Description

The route obfuscation capability mounts all admin-only API routes under a configurable prefix (LOCALESP_ADMIN_PREFIX). The well-known /api/... admin paths no longer have handlers and return 404, hiding the admin surface from route enumeration without adding authentication.

ADDED Requirements

Requirement: Admin routes are served only under a configurable prefix

The system SHALL serve admin-only endpoints exclusively under the value of LOCALESP_ADMIN_PREFIX (required, no default: the server fails fast with a clear error when it is unset; documented in .env.example, which the server auto-loads without overriding real environment variables), and SHALL NOT register handlers for those endpoints under the legacy /api paths.

Admin endpoints under the prefix:

Endpoint Method
$ADMIN_PREFIX/pendientes GET
$ADMIN_PREFIX/aprobar/:id POST
$ADMIN_PREFIX/rechazar/:id POST
$ADMIN_PREFIX/locales/:id DELETE
$ADMIN_PREFIX/reportes GET
$ADMIN_PREFIX/reportes/:id/descartar POST

Scenario: Legacy admin path returns 404 when a prefix is configured

  • WHEN LOCALESP_ADMIN_PREFIX is set to a value other than /api
  • AND a client makes a request to /api/pendientes, /api/reportes, /api/aprobar/:id, /api/rechazar/:id, DELETE /api/locales/:id or /api/reportes/:id/descartar
  • THEN the server responds with HTTP 404
  • AND no data is returned and no action is executed

Scenario: Prefixed admin path serves data to clients that know it

  • WHEN LOCALESP_ADMIN_PREFIX is set to a value other than /api
  • AND a client requests $ADMIN_PREFIX/pendientes
  • THEN the server responds with the pending proposals as before
  • AND the admin panel works unchanged because the frontend is compiled with the same single LOCALESP_ADMIN_PREFIX variable (exposed to the client via Vite envPrefix)

Scenario: Missing configuration fails fast

  • WHEN LOCALESP_ADMIN_PREFIX is not set (or empty)
  • THEN the server refuses to start with a clear configuration error
  • AND there is no default value: every deployment must choose its prefix (documented in .env.example)

Scenario: Public routes are unaffected

  • WHEN a client makes a GET request to /api/locales
  • THEN the server responds with HTTP 200 and the list of locales

Scenario: User-facing report and confirm actions remain public

  • WHEN a client makes a POST request to /api/locales/:id/reportar or /api/locales/:id/confirmar
  • THEN the endpoints behave as before, because the public website uses them (they are user features, not admin surface)

REMOVED Requirements

Requirement: Admin panel routes are fully discoverable

Reason: Security concern — admin routes should be harder to discover Migration: Admin users access the panel at /admin; its API calls go to the configured prefix — the same single LOCALESP_ADMIN_PREFIX variable at build time

MODIFIED Requirements

Requirement: Admin panel serves pending proposals

The requirement SHALL:

  1. Allow unauthenticated clients to submit proposals via /api/propuestas (unchanged)
  2. Serve the pending-proposals list from $ADMIN_PREFIX/pendientes (legacy /api/pendientes returns 404 when a prefix is configured)

Scenario: Admin views pending proposals through the panel

  • WHEN an admin opens the panel at /admin
  • THEN the panel fetches $ADMIN_PREFIX/pendientes (compiled with LOCALESP_ADMIN_PREFIX) and renders the list exactly as before

Design note: This is obscurity, not security: the prefix ships in the frontend bundle. It raises the cost of blind route enumeration only. Real authentication is explicitly deferred to a future change.