feat(P12.1): API móvil para socios con vínculo auth.users ↔ socios

.env.example

@@ -2,3 +2,11 @@
 NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
 NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
 SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
+
+# Pepper de los códigos de invitación de la app móvil (>= 32 caracteres).
+# Se concatena al código antes de hashearlo, así que NUNCA vive en la base:
+# un dump de Postgres no alcanza para hacer fuerza bruta offline sobre los
+# hashes. Generar con: openssl rand -base64 48
+# ATENCIÓN: rotarlo invalida TODOS los códigos pendientes de canje de golpe.
+# Nunca ponerle el prefijo NEXT_PUBLIC_ (quedaría expuesto en el bundle).
+INVITACIONES_PEPPER=generar-con-openssl-rand-base64-48

CHANGELOG.md

@@ -30,6 +30,20 @@ Remediación del export de advisories de Sentinello del 2026-08-04 (41 hallazgos
 
 ### Added
 
+- **API móvil para socios** (P12.1, migración `20260813000001`). Endpoints bajo `/api/mobile/v1/*` para que un socio autenticado consulte **sus propios** datos desde una app en el teléfono: perfil, cuotas sociales (pagas/impagas + resumen de deuda), compras y —si es titular— las cuotas de su grupo familiar. Son las **primeras rutas HTTP del repo**: hasta ahora todo el acceso a datos vivía en Server Actions.
+  - **El problema no era exponer los datos, era aislarlos.** El RBAC del ERP es todo-o-nada por módulo: `select_cuotas` está gateada en `get_user_modulo_permission('socios','leer')`, exactamente el mismo permiso que da lectura del **padrón entero**. Darle un rol a un socio para que vea su deuda le mostraría la de los otros 8.399. Y no existía ningún vínculo entre `auth.users` y `socios` — la tabla no tiene email, ni teléfono, ni `user_id`.
+  - **La solución es que el socio tenga cero permisos de tabla.** No se agregó **ninguna** política RLS nueva sobre `socios`/`cuotas`/`ventas`: las políticas se OR-ean entre sí y cada permisiva nueva obliga a re-verificar que no amplíe el acceso de otro. En su lugar, toda lectura pasa por una función `SECURITY DEFINER` que deriva el socio de `auth.uid()` y **no acepta ningún identificador de socio como parámetro** — sin parámetro no hay IDOR que explotar. Como la cuenta del socio no tiene filas en `usuarios_roles`, su JWT contra PostgREST directo devuelve `[]` (verificado en psql sobre `socios`, `cuotas`, `ventas` y `categorias_sociales`). Auditar la seguridad de la API es leer esas ~16 funciones, y nada más.
+  - **Dos triggers hacen que un socio no pueda ser staff.** Es la mitigación del peor caso. `trg_socios_usuarios_excluye_staff` impide vincular una cuenta que ya tenga rol del ERP; `trg_usuarios_roles_excluye_socios` es el espejo, y es el que se olvida: sin él, `updateUsuarioRole()` en la pantalla de Seguridad le asignaría "Administrador" a la cuenta móvil de un socio sin que nada lo frene. No es una convención escrita en un README, es un `EXCEPTION`.
+  - **Alta por código de invitación, no auto-registro.** El padrón no tiene emails a los que mandar nada, y DNI + nro_socio no sirve como prueba de identidad: `migrate.py` sintetizó los DNIs faltantes como `dni = nro_socio`, así que en esas filas son el mismo dato. El club emite un código desde `/socios/app-movil` (individual o masivo, con export a Excel) y lo entrega en el mostrador. Formato Crockford base32 de 10 caracteres (2^50), con el mapeo `O→0`/`I→1`/`L→1` al canjear para que un error de tipeo no sea un código inválido. En la base vive **sólo** `sha256(codigo || INVITACIONES_PEPPER)`, calculado en Node: el pepper nunca toca Postgres, así que un dump no alcanza para fuerza bruta offline. No se usa bcrypt/argon2 a propósito — el código es un token de CSPRNG, no una clave humana, y un KDF lento sólo agregaría latencia al canje legítimo.
+  - **El "un solo uso" es un `UPDATE ... WHERE usado_at IS NULL ... RETURNING`**, una sola sentencia y no un SELECT-después-UPDATE. Con dos canjes concurrentes del mismo código el segundo espera el lock de fila, reevalúa la condición al soltarlo y no matchea — verificado con dos sesiones psql simultáneas. El `INSERT` del vínculo va en la misma transacción, así que si el socio ya estaba vinculado el índice parcial único rebota y el rollback deshace también el consumo del código. El canje **crea** la cuenta (lo que permite dejar `enable_signup = false`), y si el vínculo falla después de crear el usuario Auth, el usuario se borra por compensación.
+  - **El grupo familiar falla cerrado.** Sólo el titular (`grupos_familiares.titular_id`) ve las cuotas del grupo; si el grupo no tiene titular designado, no lo ve nadie. En los datos migrados puede haber grupos sin titular y es tentador inferirlo (el más antiguo, el de menor `nro_socio`), pero eso sería inventar una regla de autorización cuyo costo de error es mostrarle a alguien la deuda de un tercero. Para que no se vuelva un ticket irresoluble, `/socios/grupos-familiares` ahora avisa cuántos grupos están así y permite filtrarlos. De los demás miembros se expone sólo nombre, categoría y deuda — nunca DNI, fecha de nacimiento ni localidad.
+  - **El middleware redirigía `/api` a `/login` con un 307.** El matcher no excluía `/api` y el guard de sesión es incondicional salvo para `/login`, así que cualquier endpoint le habría devuelto el HTML del login a un cliente que espera JSON — indistinguible de un bug del endpoint. Se arregla en dos lugares a propósito: la exclusión en el matcher (que además ahorra un round-trip a GoTrue por request) y un guard al inicio de `updateSession`, que sobrevive a que alguien edite el matcher sin acordarse de por qué estaba así.
+  - **Rate limit en tabla, no en memoria.** Vercel corre lambdas sin estado compartido: un contador de módulo arrancaría vacío en cada invocación. 10 intentos por IP cada 15 minutos, 1 hora de castigo. La IP se toma de `x-vercel-forwarded-for` y **no** de `x-forwarded-for` a secas, que el cliente puede anteponer para rotar identidad en cada request y volver el limiter decorativo. Las RPCs de canje, validación y rate-limit están revocadas de `anon` **y** de `authenticated`, así que el único camino es el route handler y el limiter no se puede saltear yendo directo a PostgREST.
+  - **Un segundo review encontró un bug de pérdida de datos que el primero no vio.** En la emisión masiva, `emitir()` guardaba los códigos en claro con `setEmitidos(res)` y acto seguido llamaba a `previsualizar()`, cuya primera línea era `setEmitidos([])`: el último write ganaba y los borraba. Como la base guarda **sólo los hashes**, los códigos de la tanda entera quedaban irrecuperables, con un toast diciendo "120 código(s) emitido(s)" al lado de un botón "Descargar Excel (0)" deshabilitado — y la única salida era reemitir, revocando de nuevo los que el operador ya hubiera repartido.
+  - **La invariante socio ≠ staff no resistía la concurrencia.** Los dos triggers hacían un `EXISTS` sobre la otra tabla sin ningún lock, así que bajo READ COMMITTED dos transacciones simultáneas no se veían y ambas commiteaban: quedaba una cuenta que era socio **y** staff, o sea con `socios:leer` — lectura del padrón entero por PostgREST directo, esquivando todas las funciones `mobile_*`. Se cierra con `pg_advisory_xact_lock(hashtextextended(user_id, 0))` como primera sentencia de ambos triggers, verificado con dos sesiones psql concurrentes (la segunda ahora bloquea y falla). No era alcanzable desde la app, pero es la invariante que la migración declara como su mitigación más importante y cualquier script con `service_role` la volvía alcanzable.
+  - El filtro de cuentas de socios en Seguridad → Usuarios reintroducía el truncamiento de 1000 filas de PostgREST que el propio cambio acababa de arreglar para `listUsers`: a partir de la cuenta 1.001 las cuentas de socios volvían a aparecer mezcladas con el staff. Ahora usa `fetchAllRows` y filtra sólo vínculos vivos, para que una cuenta desvinculada no quede invisible e inadministrable.
+  - Los handlers **nunca** propagan mensajes crudos de Postgres (el patrón `throw new Error(error.message)` de los ~48 `actions.ts`): las RPCs levantan identificadores snake_case que son contrato de API y los traduce `src/lib/api/rpc-errors.ts`; lo no mapeado es un 500 genérico con `X-Request-Id` para correlacionar en los logs. `admin.ts` gana `import "server-only"`. Documentación completa en `docs/API_MOBILE.md`.
+
 - **Precio diferenciado para socios y no socios en los ítems de venta** (migración `20260812000001`). `items_ventas` pasa de un precio a dos: `precio` (que ahora significa explícitamente *tarifa de socio*) y `precio_no_socio`. El toggle **Socio | No Socio** que ya existía en el POS pasa de sólo cambiar qué datos del comprador se piden a **determinar cuánto se cobra**.
   - **El legacy ya tenía las dos tarifas y la migración original las perdió.** `ItemsVentas` en `docs/backup.sql` tiene `ValorSocio` **y** `ValorNoSocio`, y `migration/migrate.py` importaba sólo la primera. Por eso el backfill no aplica un porcentaje parejo: recupera el `ValorNoSocio` real de los 210 ítems legacy, matcheando por **primary key** —el uuid5 determinista que asignó el importador— y no por nombre, que en `items_ventas` no es único. De esos 210, 190 tenían ambas tarifas iguales y 20 diferían, con ratios que van de 1.17x a **4.0x** (*Alquiler Quincho Cerrado*: $48.000 socio / $192.000 no socio). Un `precio * 1.2` uniforme habría inventado 20 precios y, peor, habría dejado en **$0 para el no socio** a los 15 ítems que el club cobra gratis al socio y caro al resto (*Derecho de línea Galería*: $0 / $28.000; *Idoneidad de tiro*: $0 / $46.000) — justo los casos donde la tarifa de no socio es la única que importa. El `+20%` queda sólo como default de lo que se cargue de ahora en más.
   - **La tarifa la elige el servidor, no el browser.** `registrar_venta` ya resolvía el precio desde `items_ventas` (el cliente sólo manda `{item_id, cantidad}`), así que el `CASE` vive ahí: `p_socio_id IS NOT NULL` → `precio`, cualquier otro caso → `precio_no_socio`. Un `cliente` del histórico cuenta como no socio: la tabla `Clientes` del legacy era la de compradores sueltos. El `CASE` va en un `CROSS JOIN LATERAL` para no repetirlo en `precio_unitario` y en `subtotal`, que es la forma clásica en que estas dos copias se desincronizan. La función se redefine con `CREATE OR REPLACE` manteniendo la firma de 8 argumentos: sin `DROP` sobreviven los `GRANT` y PostgREST no queda con dos overloads.

PROGRESS.md

@@ -149,6 +149,14 @@
 
 ---
 
+## FASE 12 — App móvil para socios
+
+| ID | Tarea | Estado | Fecha |
+|----|-------|--------|-------|
+| P12.1 | API `/api/mobile/v1/*` (perfil, cuotas, compras, grupo familiar) + vínculo `auth.users ↔ socios` con códigos de invitación y pantalla de emisión en el ERP | ✅ | 2026-08-13 |
+
+---
+
 ## Bloqueadores activos
 
 _Ninguno por ahora._