Políticas IT NR

Reglas prácticas para features nuevas en Wealth Navigator y Wealth Mobile

Uso interno

Destinatarios: desarrollo, operaciones y soporte. Estas políticas se basan en la arquitectura real de Wealth Navigator (web/API FastAPI + React) y Wealth Mobile (Flutter iOS/Android). No sustituyen la documentación canónica de cada repo; la resumen para uso diario.

1. Alcance y principios

  • Mínimo privilegio: cada feature hereda el modelo recurso:accion:alcance (own → assigned → all). No ampliar alcance “por comodidad”.
  • Fail-closed en producción: 2FA obligatorio, CORS restringido, Integrity en Android, HTTPS fijo a https://api.newroadai.com en builds prod de mobile.
  • Sin secretos en git ni en el cliente: keys, tokens de custodia, webhooks, Admin SDK Firebase y keystores viven en env/secrets del servidor o CI.
  • IDs opacos: UUIDs públicos en contratos browser/mobile; nunca exponer PKs secuenciales ni inventar IDs en el cliente.
  • Elevado riesgo por defecto: CRM, onboarding/NAF, documentos, banca, ETL, exports, retiros, recibos de referral y simulación de usuario requieren revisión explícita.

2. Autenticación, sesiones y MFA

Wealth Navigator (web)

  • Login con OTP por email (challenge JWT → cookie HttpOnly newroad_session). Google Sign-In solo acorta OTP para roles acotados (Investor, Advisor, Intern Advisor, Advisor Assistant, Referral).
  • Operaciones de control/admin/ETL deben respetar mfa_verified. No debilitar 2FA ni usar DISABLE_2FA=true fuera de local.
  • Simulación de usuario (user:simulate:all) es solo lectura (~30 min). No ampliar writes sin revisión de seguridad.
  • Basic Auth está rechazado a propósito: no reintroducirlo para “saltar” MFA.

Wealth Mobile

  • Auth solo password contra /api/v1/mobile/auth/*. Google Sign-In no existe en mobile.
  • La contraseña nunca se persiste. El JWT va en memoria; a Keystore/Keychain solo si el usuario activa biometría.
  • Tras ~30s en background, forzar reingreso con remember-me. Pantallas de documentos deben reautenticar al entrar.
  • Política de password nueva: mínimo 12 / máximo 128 (alineada al backend). Login legado puede aceptar ≥8 solo para contraseñas antiguas.
  • Roles móviles efectivos: Investor y Referral. Usuario dual se resuelve como Referral. No mezclar shells de navegación.

3. Roles, permisos y alcance de datos

  • Fuente de verdad de permisos: nomenclatura recurso:accion:alcance en Wealth Navigator. Frontend y backend deben coincidir; una ruta nueva sin permiso = bug.
  • Investor: solo own (portfolios, cuentas, posiciones, transacciones).
  • Advisor / Intern / Assistant: datos de clientes assigned, no firm-wide.
  • Operation / Backoffice / Control / Admin: privilegios altos (ETL, CRM write, roles). Cambios de rol o execute de ETL requieren control de cambios.
  • En APIs: filtrar por alcance antes de resolver IDs. No autorizado o inexistente → mismo 404 (anti-enumeración / IDOR).
  • El “blur” de privacidad en portfolios es UX para screen-share, no control de acceso.

4. PII, KYC, banca y datos financieros

  • Tratar como confidencial: nombre, email, teléfono, dirección, tax_id/DNI, cuentas bancarias/CCI, contratos NAF, documentos DNI/contratos, holdings, cashflows, comisiones y fees.
  • Documentos KYC/AML: cifrado AES-256-GCM en storage; usar servicios existentes, no inventar rutas de archivo en claro.
  • Formularios públicos NAF: tokens con capability, rate-limit, sin KYC en contrato público. Compartir el link solo con el cliente destinatario y revocar al terminar.
  • Soporte público: no pedir ni persistir contraseñas, OTP, tokens ni números de cuenta completos.
  • Exports PDF/XLSX y factsheets compartidos: jobs con UUID del solicitante; tokens de share opacos y con vigencia.
  • Mobile — retiros: monto, destino bancario, teléfono y comentarios son datos de ops/AML; no loguear el body.
  • Mobile — referrals: PII del prospecto + DNI + prospect_consent_confirmed obligatorio. Recibos PDF ≤10 MB con Integrity en Android.
  • Telemetría: sendDefaultPii=false; no screenshots/replay en mobile; no loguear headers/bodies Dio; correlacionar con X-Request-ID.

5. Secretos, entornos y despliegue

  • Producción: API api.newroadai.com, front www / liberty. Staging aislado (DB/Redis). Previews de Pages no deben pegarse a la API de producción.
  • CORS prod solo orígenes allowlist (www.newroadai.com, liberty.newroadai.com). Nunca localhost ni *.pages.dev contra prod.
  • No poner en VITE_* ni dart-defines: URLs de Google Sheets /exec, webhooks Kapso, DB, Flex IBKR, service accounts, Admin Firebase.
  • Custodiar: IBKR Flex, AIS, Kapso/WhatsApp, Resend, Google OAuth/Calendar, Play Integrity, keystores Android, Firebase client configs.
  • CI: gitleaks; no imprimir .env en logs de deploy. Rotar ante cualquier exposición.
  • Mobile prod: origin API exacto HTTPS; cleartext bloqueado; channel internal vs production; nunca ship PLAY_INTEGRITY_NEGATIVE_TEST fuera de QA interna.
  • Contratos nuevos preferir /api/v2 con UUIDs públicos; extender /api/v1 solo si es inseparable. Compartir deps de auth/RBAC (deps.py), no bifurcar.
  • OpenAPI /docs deshabilitado en producción; no reactivarlo.
  • Webhooks Kapso: verificar HMAC del body; fallar cerrado sin secreto.
  • Passwords temporales: solo generados en servidor; no devolver al SPA; no defaults tipo password123.
  • Módulos de alto impacto (ETL, IB Gateway, Admin roles, CRM master, payments, market brief masivo): documentar en el mismo PR y seguir runbooks / module-impact-map.
  • Audit logs: mutaciones y auth/admin/etl/mobile se persisten; no loguear secretos (usar redaction existente).
  • Migraciones compatibles con blue/green; no romper lectura durante el deploy.

7. Reglas específicas — Wealth Mobile

  • Stack: Flutter (no RN). Personas Investor vs Referral con routers separados.
  • Operaciones sensibles deben decidir si requieren Play Integrity (login, reset password, create referral, receipts, documents, welcome PDFs). iOS App Attest aún puede estar en modo exempt: documentar el riesgo.
  • Documentos: usar EncryptedDocumentCache (AES-GCM, TTL plaintext ~10 min, wipe en resume/logout). No SharedPreferences para tokens.
  • No reintroducir permisos amplios de storage/media. Enlaces externos solo HTTPS (parseHttpsUri).
  • Nora y copy de tiendas: no prometer asesoría/retornos. Legal vía disclosures existentes.
  • Account deletion no es self-serve in-app: canal de soporte / proceso operativo NR.
  • Reabrir Documents en Android investor requiere revalidar checklists Play (producto y seguridad) antes de promover.
  • Evidence de release: sin tokens, Integrity payloads, FCM, device IDs ni pantallas con PII real.
  • Certificate pinning no está implementado: no añadirlo sin plan de rotación/ops.

8. Checklist antes de abrir un PR / release

Permisos ¿Endpoint/ruta con RBAC y filtro own/assigned/all? ¿404 anti-IDOR?
Secretos ¿Nada sensible en Vite/dart-define/git? ¿Env documentado en ejemplo sin valores reales?
PII / logs ¿Sin bodies, OTPs, tax IDs, cuentas en logs/Sentry? ¿Consent en referrals?
Auth ¿MFA donde corresponde? ¿Mobile: Integrity / biometría / shells de rol intactos?
Entorno ¿CORS/API origin correctos? ¿Prod fail-closed? ¿Staging para previews?
Docs / ticket ¿Cambio de alto riesgo enlazado a Trello (implementación/petición) y docs del repo?

9. Soporte, tickets e incidentes

  • En tickets (ver página Trello / Ticketing): incluir app, entorno, versión/release-channel, X-Request-ID, rol afectado y pasos. Prohibido pegar passwords, OTP, JWT, dumps financieros o pantallas con PII de clientes reales.
  • Escalamiento de acceso/cuenta: flujos oficiales de reset móvil o soporte web; no editar DB “a mano” desde el repo mobile.
  • Simulación de usuario solo para troubleshooting, con salida limpia de la sesión simulada.
  • Ante exposición de secretos o posible IDOR: rotar credenciales, revisar audit/Sentry, y no cerrar hasta verificación.
  • Contacto soporte producto (público): canales documentados en newroadai.com; el email operativo de desarrollo no sustituye el proceso de borrado/acceso legal.

Última actualización orientativa: agosto 2026. Ante conflicto, prevalecen AGENTS.md, docs de seguridad y matrices de permisos de cada repositorio NewRoad.