adaptador-planilhas/docs/decisions/0007-ambiente-logico-e-auth-de-homologacao.md

0007 — Ambiente lógico e autenticação de homologação

Contexto

next start força NODE_ENV=production. Até aqui o módulo só conhecia dois estados: NODE_ENV=production ou não. Consequência prática: em homologação a autenticação local sem senha ficava desligada (correto) e o módulo exigia o login central do Elo Pro (que ainda não existe), sem terceira opção. Homologação ficava sem caminho de entrada.

Além disso, nada no repositório gravava o cookie elo_pro_workspace_id, lido como origem do workspace ativo. Mesmo com sessão válida, a resposta seria sempre "sem workspace".

Decisão

1. ADAPTER_ENV com três valores: development, staging, production. É independente de NODE_ENV, que continua production em homologação para manter o build otimizado. Toda política passa a derivar de ADAPTER_ENV.

2. Homologação autentica com Supabase Auth real, em um projeto Supabase exclusivo de homologação, via signInWithPassword em /api/auth/staging/session. Há senha, emitida e validada pelo Supabase. O Adaptador continua sem tabela de usuário, senha, cadastro ou sessão própria.

3. ADAPTER_DEV_AUTH só existe em development. Não é configuração: em staging e production o provedor de desenvolvimento não entra na lista de provedores, e ADAPTER_DEV_AUTH=1 faz o start ser recusado.

4. Contrato de identidade explícito em src/server/auth/identity-provider.ts. Trocar o Supabase de homologação pelo SSO do Elo Pro é adicionar uma implementação; nenhum outro arquivo conhece o mecanismo.

5. Workspace é resolvido no servidor, por associação real. O cookie é preferência, não prova: resolveWorkspace só o aceita quando corresponde a uma linha de workspace_members lida sob RLS. Sem associação, não há workspace. Com várias, a pessoa escolhe em /selecionar-workspace, e POST /api/auth/workspace grava o cookie apenas depois de confirmar a associação.

Alternativas descartadas

• Habilitar o dev auth em homologação. Rejeitada: homologação é pública, e autenticação sem senha em host público é uma porta aberta.
• Aceitar o cookie de workspace como autorização. Rejeitada: transformaria um valor editável pelo cliente em credencial. O custo de reler a associação por requisição é uma consulta indexada.
• Usar o projeto Supabase de produção com usuários de teste. Rejeitada: compartilharia a service role entre ambientes.
• Inferir o ambiente de SENTRY_ENVIRONMENT. Rejeitada: observabilidade e política de segurança são decisões diferentes; a mesma variável governando as duas foi o que fez o namespace do Redis colidir entre ambientes.

Consequências

• ADAPTER_ENV passa a ser obrigatória nos ambientes implantados, e ADAPTER_APPLY_IDENTITY_SHIM passa a ser uma decisão explícita.
• Homologação tem seu próprio projeto Supabase, bucket, banco, Redis e ambiente Sentry.
• O 0002-sso-topology.md continua valendo para produção. Esta decisão acrescenta o degrau de homologação, sem substituí-lo.