collective-lists/plan/fase-1-auth-colectivo.md

Fase 1 — Autenticación y Colectivo ✅

Estado: Completa (pendiente: detección automática de idioma desde Accept-Language)
Duración estimada: 2–3 semanas
Objetivo: la base del dominio. Sin esto no existe nada más.

1.0 Tests — escritos y verdes ✅

A-series (auth), B-series (colectivo), F-series (aislamiento) están cubiertas por:

• Vitest integration (packages/test-utils/tests/rls-{collective,isolation}.test.ts) — lectura por rol, invitación, accept_invitation(), aislamiento no-miembro
• pgTAP (supabase/tests/001_accept_invitation.sql, 003_promote_on_admin_leave.sql) — happy path y casos de error de accept_invitation, promoción automática al último admin
• Playwright E2E (apps/web/tests/e2e/auth.test.ts) — redirect a Keycloak, login full OAuth, ver colectivo en sidebar, sign-out, login como guest

1.1 Base de datos

• Migración: tabla users — espejo de auth.users de Supabase, poblada por trigger al primer login OIDC:
  • display_name, email
  • language: enum(en | es) — default en, sobrescrito por preferencia de navegador en primer login
  • avatar_type: enum(initials | emoji | upload) — default initials
  • avatar_emoji: text | null
  • avatar_url: text | null — URL firmada de Supabase Storage
• Migración: tabla collectives con campos id, name, emoji, created_by, created_at
• Migración: tabla collective_members con role: enum(admin | member | guest)
• Migración: tabla collective_invitations con token, expiración y estado
• RLS completo — políticas críticas:
  • Un usuario solo puede leer colectivos a los que pertenece
  • Solo administradores pueden insertar en collective_invitations
  • Solo administradores pueden actualizar roles en collective_members
  • Un usuario solo puede actualizar su propia fila en users
• Trigger: on_auth_user_created — sincroniza el perfil de Keycloak (display_name, email) a users en cada login
• Trigger: promoción automática al miembro más antiguo si el último admin elimina su cuenta (RN-10)
• Función SQL: is_active_member(collective_id, user_id) — usada en todas las políticas RLS
• Bucket Supabase Storage: avatars — privado, acceso vía signed URLs, un fichero por usuario ({user_id}/avatar)

1.2 Integración Keycloak → Supabase

✅ DECISIÓN: Opción B — GoTrue como proxy OIDC. GoTrue recibe el token de Keycloak, lo valida y emite su propio JWT de Supabase. auth.uid() resuelve al UUID de GoTrue (que mapea al sub de Keycloak). Esto mantiene auth.users de Supabase poblado y permite usar todas las helpers de GoTrue.

• Configurar Keycloak como OIDC Identity Provider en GoTrue (infra/docker-compose.dev.yml — GOTRUE_EXTERNAL_KEYCLOAK_*)
• Flujo: signInWithOAuth({ provider: 'keycloak' }) → Keycloak PKCE → GoTrue callback → Supabase session
• Verificar que auth.uid() en las políticas RLS resuelve correctamente — ✅ curl acceptance test: los 5 usuarios autenticados vía Keycloak→GoTrue tienen sub correcto y las políticas RLS devuelven solo sus datos
• Test de integración: token de Keycloak → exchange con GoTrue → query a Supabase con RLS → respuesta correcta — ✅ todos los 5 usuarios pasan

1.3 Invitaciones (sin email)

✅ DECISIÓN: sin email. Las invitaciones se crean como un link que el admin copia manualmente y comparte por cualquier canal (WhatsApp, etc.). No se integra Resend ni se envían emails.

• collective_invitations tiene token único (UUID), expires_at, role, y accepted_at
• Pantalla /collective/manage genera el link de invitación y muestra un botón "Copy link"
• /invitation/[token] — el invitado abre el link, se autentica si no lo está, y acepta
• Lógica de aceptación via función SQL accept_invitation(p_token) SECURITY DEFINER (no Edge Function)

1.4 Internacionalización (i18n)

Librería: Paraglide JS (@inlang/paraglide-sveltekit). Compile-time, tree-shaken por idioma, sin overhead en runtime.

• Instalar y configurar @inlang/paraglide-sveltekit con el plugin de Vite
• Crear ficheros de mensajes: messages/en.json y messages/es.json
• Configurar detección de idioma: Accept-Language header en primer load → guardado en users.language tras login
• Cambio de idioma en runtime: actualizar users.language en Supabase + llamar a setLanguageTag() de Paraglide — sin recarga de página
• Traducir todas las cadenas UI de la Fase 1 (onboarding, gestión de colectivo, settings)

Las cadenas de UI van en messages/. Nunca hardcodear texto visible al usuario directamente en componentes.

1.5 Frontend

• Integración de Supabase OAuth en SvelteKit (PKCE, no keycloak-js):
  • supabase.auth.signInWithOAuth({ provider: 'keycloak' }) — compatible con Safari sin iframes
  • Store Svelte auth — expone currentUser, authLoading, isAuthenticated, displayName
  • login() redirige a Keycloak vía GoTrue; callback en /auth/callback intercambia el code
  • Refresco automático de sesión por el cliente de Supabase (localStorage)
• Rutas protegidas: (app)/+layout.ts con ssr: false que redirige si no hay sesión
• Flujo de onboarding post-primer-login:
  • Detectar si el usuario no pertenece a ningún colectivo → redirigir a /onboarding
  • Opción A: Crear nuevo colectivo (nombre + emoji)
  • Opción B: Pegar link de invitación recibido
• Pantalla /collective/manage — miembros, roles, botón "Generate invite link" (copia al clipboard), expulsar
• Pantalla /invitation/[token] — aceptar invitación (el usuario debe estar autenticado)
• Selector de colectivo activo en la barra lateral — un usuario puede pertenecer a varios colectivos y cambiar entre ellos
• Store Svelte collective — colectivo activo, lista de miembros, rol del usuario actual, lista de todos los colectivos del usuario
• Pantalla /settings — configuración de usuario:
  • Campo display name (input de texto, guardado automático con debounce)
  • Selector de avatar con tres modos:
    • Initials — preview generado en tiempo real desde el display name
    • Emoji — grid de 32 emoji curados, tap para seleccionar
    • Upload — input de fichero; recorte en el navegador 1:1 con cropperjs; subida a Supabase Storage bucket avatars
  • Selector de idioma (English / Español) con efecto inmediato
  • Enlace externo a Keycloak Account Console para cambio de email/contraseña
• Componente Avatar.svelte — renderiza según avatar_type: initials (color determinista por hash del nombre), emoji, o <img> con fallback a initials

Auto-registro: Self-registration está habilitado en Keycloak. Un usuario sin cuenta que recibe un link de invitación puede registrarse en la pantalla de Keycloak y volver al callback de invitación automáticamente.

1.Z Verificación final ✅

• just test-all — 0 failures (los 5 usuarios hacen login, A/B/F-series verdes)

Criterio de aceptación: los 5 usuarios de prueba pueden autenticarse contra Keycloak, llegar a la app con sesión activa, y auth.uid() en Supabase resuelve correctamente para las políticas RLS.

---