Auth y Deep Link en Native

Estado

Flujo OAuth oficial orientado a BFF web.

• Ruta oficial actual: native -> Zauru authorize -> deep link callback -> web BFF exchange.
• PKCE: pendiente de soporte por proveedor.
• Happy path oficial: BFF-first.
• direct existe solo como escape hatch técnico deprecated, no como setup normal del proyecto.
• En esta fase, mobile no hace graphql.json ni GraphQL directo.
• Mobile solo persiste metadata de zauruSession si el BFF/backend la devuelve.

Qué pasa en development build vs producción

• Development build (Expo Dev Client): al abrir por primera vez en iPhone puede aparecer una pantalla para pegar/abrir la URL de Metro. Es normal en dev y no aparece en producción.
• Producción (EAS/App Store/TestFlight): el bundle ya va embebido/actualizable por OTA; no existe ese panel de conexión a Metro.

Esquema esperado

<app-scheme>://auth/callback

Ruta oficial de intercambio (BFF)

1. App abre authorize con redirect_uri=<app-scheme>://auth/callback.
2. Zauru devuelve code al deep link de la app.
3. App envía code al backend web:
   • POST /api/mobile/auth/exchange
4. Web valida/intercambia con proveedor usando client_secret solo en servidor.
5. Web exige validación adicional en BoostAPI.
6. Web devuelve sesión mobile:
   • accessToken corto
   • refreshToken rotativo
   • expiresAt
   • user con metadata de acceso de BoostAPI
   • clientKind = "mobile"
   • zauruSession real si backend ya la devuelve; si no, mobile usa un fallback controlado
7. App persiste sesión en almacenamiento seguro.

Relación entre sesión CRM y sesión Zauru

• La sesión general mobile sigue dependiendo de accessToken + refreshToken.
• zauruSession es metadata de capacidad para módulos Zauru-backed.
• Mobile no guarda el JWT crudo de GraphQL en SecureStore.
• Biométricos siguen siendo solo unlock local.
• Mobile no resuelve Zauru por su cuenta; backend hace reconcile y expone snapshot.
• Si más adelante entra un módulo Zauru-backed a Expo, deberá reaccionar a:
  • missing
  • ready
  • expiring_soon
  • expired
  • entity_mismatch usando el snapshot ya devuelto por backend/BFF.

Variables mínimas

Native

• EXPO_PUBLIC_AUTH_ZAURU
• EXPO_PUBLIC_CLIENT_ID
• EXPO_PUBLIC_REDIRECT_URI
• EXPO_PUBLIC_WEB_BFF_BASE_URL
• EXPO_PUBLIC_WEB_BFF_DEV_BASE_URL opcional para dispositivo físico en dev

Valores operativos:

• dev: EXPO_PUBLIC_AUTH_ZAURU=https://zauru-oauth-staging.herokuapp.com
• prod: EXPO_PUBLIC_AUTH_ZAURU debe apuntar a la base OAuth productiva aprobada

Nota:

• aunque en staging el login visible pueda verse como https://zauru-oauth-staging.herokuapp.com/login, en .env guardamos la base del proveedor porque native construye /dialog/authorize y /api/userinfo desde EXPO_PUBLIC_AUTH_ZAURU.

Web (BFF)

• CLIENT_SECRET
• MOBILE_JWT_SECRET
• MOBILE_REFRESH_SECRET
• MOBILE_ALLOWED_REDIRECT_URIS
• MOBILE_AUTH_REVOCATION_STORE_PATH

Nota:

• EXPO_PUBLIC_AUTH_MODE ya no es parte del contrato principal de setup. Si todavía existe localmente, se considera solo compatibilidad temporal.

Configuración recomendada dev/prod

1. Flujo oficial de dev mobile:
   • npm run dev desde la raíz
   • ese comando corre en modo manual BFF por defecto (BOOST_AUTO_BFF=0)
2. Flujo manual recomendado:
   • levantar apps/web
   • abrir cloudflared tunnel --url http://localhost:3000 --no-autoupdate
   • fijar URL con npm run dev:mobile:set-bff-url -- https://<url>.trycloudflare.com
   • correr npm run dev:manual-bff
3. Flujo automático legacy opcional:
   • npm run dev:auto-bff
4. Producción:
   • EXPO_PUBLIC_WEB_BFF_BASE_URL=https://crm.roo.com.gt
5. Importante:
   • http://localhost:3000 no funciona en iPhone físico para el BFF
   • prod no usa cloudflared, ni Expo tunnel, ni EXPO_PUBLIC_WEB_BFF_DEV_BASE_URL

Prerrequisitos locales del flujo oficial

• cloudflared instalado
• Xcode.app seleccionado, no CommandLineTools:
  • sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
• xcrun simctl list devices debe funcionar

Dos túneles distintos en dev

• BFF tunnel
  • normalmente lo abres manualmente con cloudflared
  • expone apps/web
  • actualiza apps/native/.env.local con EXPO_PUBLIC_WEB_BFF_DEV_BASE_URL
• Metro/dev-client tunnel
  • lo abre Expo con --tunnel
  • depende de Expo tunnel/ngrok

Regla:

• si falla simctl, el problema es del entorno local/Xcode
• si falla ngrok/body, el problema es del tunnel de Expo, no del BFF

Fallback mínimo de emergencia

• npm run dev:lan --workspace=apps/native
• solo usarlo cuando falle el modo manual-bff oficial
• no forma parte del happy path del proyecto

Guardrails

• No exponer secretos en cliente.
• Persistencia de sesión en almacenamiento seguro.
• Rotación de refresh token en cada refresh.
• client_kind = "mobile" debe viajar en exchange/login hacia BoostAPI.
• graphql_jwt de Zauru no debe persistirse en cliente.
• El refresh normal sigue yendo por BFF.
• Mobile hereda contratos y metadata de backend; no inventa una capa paralela de auth o entidad.

Automatización recomendada para equipo

Flujo oficial actual (manual-bff)

Desde la raíz del monorepo:

npm run dev

Luego:

1. levanta apps/web (si no estaba arriba);
2. abre túnel HTTPS manual hacia http://localhost:3000;
3. fija apps/native/.env.local con npm run dev:mobile:set-bff-url -- <url>;
4. deja native en Metro LAN.

Nota: .env.local se usa porque la URL del túnel cambia con frecuencia y los scripts la sobrescriben en cada ejecución.