MVP 1 - Autenticacao - Tecnico

Topologia

Backend

Rotas REST:

• POST /auth/register
• POST /auth/login
• POST /auth/logout
• POST /auth/password/forgot
• POST /auth/password/reset
• GET /user/me

Arquivo de registro:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/auth/routes.py

Web

Paginas:

• /login
• /register
• /forgot-password

Arquivos:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/pages/login.vue
• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/pages/register.vue
• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/pages/forgot-password.vue

App

Telas:

• /(public)/login
• /(public)/forgot-password

Arquivos:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/app/(public)/login.tsx
• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/app/(public)/forgot-password.tsx

Backend: fluxo real

Login

Arquivo central:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/auth/login_resource.py

Comportamento:

• valida credenciais exclusivamente por email
• monta contexto de tentativa de login
• consulta guard de limite de tentativas
• verifica senha
• emite JWT
• persiste current_jti do usuario

Implicacao:

• o backend trabalha com uma nocao de token atual valido por usuario
• isso ajuda a invalidar sessoes antigas ou divergentes

Cadastro

Arquivo central:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/auth/register_resource.py

Comportamento:

• checa email duplicado
• pode ocultar conflito, conforme politica de seguranca
• grava senha com hash
• opcionalmente persiste investor_profile

Recuperacao de senha

Arquivo central:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/controllers/auth/forgot_password_resource.py

Comportamento:

• resposta neutra
• reaproveita guard de anti-abuso
• nao confirma existencia da conta

Backend: validacao

Schemas:

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-api/app/schemas/auth_schema.py

Regras relevantes:

• login exige senha e email valido
• email e normalizado para lowercase
• reset de senha exige token e senha forte

Frontend web

Sessao

• store simples em Pinia:
• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/stores/session.ts

Adapter HTTP

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-web/app/composables/useAuth/api.ts

Observacao tecnica importante

No codigo atual, web chama:

• POST /auth/forgot-password

Mas a API exposta no backend esta registrada como:

• POST /auth/password/forgot

Isso e um drift tecnico que precisa ser resolvido.

App mobile

Sessao

• Zustand:
• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/stores/session-store.ts

Persistencia

• secure storage via helper de sessao
• bootstrap no carregamento do app:
• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/hooks/use-session-bootstrap.ts

Mutations

• /tmp/auraxis-platform-mvp1docs-p5AMyw/repos/auraxis-app/hooks/mutations/use-auth-mutations.ts

Backend: contexto autenticado e bootstrap

Rotas relevantes:

• GET /user/me
• GET /user/bootstrap

Ownership final do bloco ARC-08:

• GET /user/me com X-API-Contract: v3
• retorna apenas contexto autenticado canônico
• agrupado em identity, profile, financial_profile, investor_profile e product_context
• nao aceita semantica de colecao como page, limit, status e month
• GET /user/bootstrap
• agregado explicito para home/frontend
• expõe transactions_preview e wallet resumida
• aceita apenas transactions_limit como ajuste de preview
• colecoes canônicas seguem em seus domínios:
• /transactions
• /wallet

Backend: deprecação controlada do legado

Janela atual de deprecação em GET /user/me:

• contratos v1 e v2 continuam funcionando temporariamente
• respostas legadas saem com:
• Deprecation: true
• Sunset: Tue, 30 Jun 2026 23:59:59 GMT
• X-Auraxis-Successor-Contract: v3
• X-Auraxis-Successor-Endpoint: /user/bootstrap

Implicacao arquitetural:

• /user/me deixa de ser endpoint mini-dashboard
• o bootstrap de tela passa a ser responsabilidade explicita de /user/bootstrap
• REST e GraphQL compartilham o mesmo core tipado de contexto autenticado
• a migracao pode ser auditada por métricas de uso do legado antes do corte final

Riscos tecnicos atuais

1. drift de rota no forgot password entre backend e frontends
2. a migração dos consumidores para GET /user/me v3 e GET /user/bootstrap ainda precisa ser concluída
3. o legado de /user/me continua exposto durante a janela de sunset, então a instrumentação precisa ser observada
4. web e app ainda nao mostram claramente estados avancados como sessao expirada ou refresh token
5. sessao no web e simples e nao evidencia persistencia robusta no codigo mostrado

Diagnostico pre-FastAPI

Causa raiz

• autenticacao cresceu por compatibilidade, sem uma politica final de identidade do login;
• o backend ainda aceita email ou name, mas apenas email e unico no modelo;
• a politica de sessao atual e single-session via current_jti, mas isso nao esta documentado como regra de produto;
• parte do contexto autenticado foi corrigida no ARC-08, mas o custo de leitura e a semantica de cada rota ainda precisam ser estabilizados.

Problema

• login por name pode ser ambiguo se houver usuarios com nomes repetidos;
• canais e stakeholders nao conseguem inferir se multi-dispositivo e suportado ou se o comportamento atual e intencional;
• /user/me, /user/profile e /user/bootstrap ja melhoraram, mas ainda precisam de ownership e custo previsivel antes da migracao para FastAPI.

Solucao planejada

1. tornar email o identificador canônico de autenticacao;
2. tratar login por name apenas como compatibilidade transitória, com deprecação observável;
3. explicitar na docs a politica atual de sessao (current_jti) e decidir se ela continua no MVP 1 ou se sera substituida;
4. otimizar GET /user/me v3 para carregar apenas profile/contexto, deixando wallet e preview apenas no bootstrap;
5. manter docs REST e GraphQL coerentes com essa ownership.

Hardening final entregue no API18.1

No programa API18, a superficie de autenticacao foi estabilizada com estas decisoes:

• email passou a ser o identificador canônico exclusivo para login;
• name foi removido do contrato de autenticacao em REST e GraphQL;
• o schema de login passou a exigir email valido;
• OpenAPI/Scalar, bundle GraphQL e collection do Postman foram alinhados ao contrato final;
• a telemetria de login agora registra apenas autenticacao por email;
• a ambiguidade tecnica de autenticacao por name deixou de existir antes da migracao para FastAPI.

Isso fecha a superficie de auth do MVP 1 antes da migracao para FastAPI.