Inicio do Projeto Piloto

docs/spreadsheet-adapter/11-auth-topology.md

@@ -0,0 +1,26 @@
+# Topologia de sessão
+
+O Adaptador não implementa IdP nem OAuth próprio e não copia cookie entre domínios.
+
+## Cenários
+
+| Cenário | Comportamento |
+| --- | --- |
+| Mesmo domínio, subpaths | Cookie Supabase e `elo_pro_workspace_id` já visíveis. `/login` só redireciona se a sessão não existir |
+| Subdomínios | Exige cookie no domínio pai, configurado na Elo Pro. O Adaptador não redefine o domínio do cookie |
+| Domínios separados | O login central emite a sessão Supabase. O retorno usa `returnTo` apenas para host permitido |
+| Redirect central | `ELO_PRO_LOGIN_URL` recebe `returnTo` |
+| Sessão Supabase compartilhada | `getUser` lê os cookies `sb-*` já presentes |
+
+## returnTo
+
+`safeReturnPath` aceita somente caminho relativo interno. `https://`, `//` e host fora de `ELO_PRO_APP_URL` / `AUTH_ALLOWED_RETURN_HOSTS` voltam para `/adaptador`.
+
+`/login` em produção redireciona para o login central. A tela local com identidades de desenvolvimento só aparece quando `ADAPTER_DEV_AUTH` está ligado fora de produção.
+
+## Sessão e módulo
+
+- Sem cookie de sessão: anônimo, 401 nas APIs.
+- Cookie presente e usuário ausente: `session_expired`, mensagem para entrar de novo.
+- Autenticado sem membership ou sem workspace: bloqueio, sem operar planilha.
+- Módulo desligado: rotas voltam ao painel e APIs respondem `FEATURE_DISABLED`.