req-217 — Módulos distribuídos: confirmação de origem e chave de sessão no canal

Hoje cada requisição do canal é assinada com o segredo da instalação (HMAC, carimbo de tempo, nonce). Quem obtiver esse segredo fala pelo Central com o site do cliente, ou pelo…

Status: in-review (validada no Lab em 2026-10-03; relatório em BATCH-225)
Modo de Autonomia: autonomo_monitorado
Lote Alvo: BATCH-225
Data de Criação: 2026-10-03
Origem: Engenheiro Chefe Humano no chat, revisando a resposta de segurança da REQ-097 do conn2flow-site.

Pedido do Humano

"Uma coisa que você pode fazer é um handshake tanto do distribuído quanto do central. Mesmo que fuja a chave, tem que ser obrigatoriamente o [REDACTED] identificado. O central quer iniciar uma conexão, manda uma requisição; o [REDACTED]ído faz uma conexão perguntando: esse aqui é você mesmo? [...] Aí depois, quando os dois têm essas duas conferências, mesmo que sumam com a chave de segurança de comunicação, não consegue acessar a rede. Ou então me explica o que pode ser melhor que isso." Trocas periódicas de chave: "ok".

Problema

Hoje cada requisição do canal é assinada com o segredo da instalação (HMAC, carimbo de tempo, nonce). Quem obtiver esse segredo fala pelo Central com o site do cliente, ou pelo cliente com o Central, de qualquer lugar.

Escopo

Confirmação de origem. Quem quer falar (A) cria um desafio de uso único (60 s) e pede a abertura (abrir). Quem recebe (B) não confia no pedido: liga de volta para o endereço que ele tem cadastrado para A (central-url no cliente; url do cadastro no Central) e pergunta se o desafio é de A (confirmar). Só com o "sim" de A, B abre a sessão.
Chave de sessão. B devolve uma chave de sessão aleatória (cifrada para A), válida por 15 minutos. Toda requisição comum passa a ser assinada com ela (X-C2F-Session); o segredo da instalação só serve para abrir sessão. A chave de trabalho é trocada sozinha a cada 15 minutos.
Exigência no receptor. Com a confirmação ligada (padrão do config.php, MODULO_DISTRIBUIDO_ORIGIN_CHECK), requisição sem sessão válida é recusada (401). Sessão de outra instalação é recusada.
Retomada. Sessão recusada (401, antes de executar qualquer coisa) é reaberta e a requisição repetida uma vez.
Testes de unidade com as duas pontas simuladas, incluindo o ataque com a chave roubada.

Critérios de aceite

CA-1: com o segredo da instalação, mas fora do endereço cadastrado, não se abre sessão em nenhuma das direções.
CA-2: requisição comum sem sessão, com sessão vencida, forjada ou de outra instalação é recusada.
CA-3: painel, troca de login, estado da conta, rotinas e webhooks seguem funcionando no Lab (roteiros dos módulos distribuídos).
CA-4: com MODULO_DISTRIBUIDO_ORIGIN_CHECK=false o canal volta ao modo anterior (compatibilidade durante a publicação).

Fora do escopo

Chaves assimétricas (Ed25519) e TLS mútuo: propostos como próximo passo no relatório.
Rotação automática do segredo da instalação (continua manual no [REDACTED] do site).

# req-217 — Módulos distribuídos: confirmação de origem e chave de sessão no canal
- **Status:** `in-review` (validada no Lab em 2026-10-03; relatório em [BATCH-225](../../implementation/archive/BATCH-225.md))
- **Modo de Autonomia:** `autonomo_monitorado`
- **Lote Alvo:** `BATCH-225`
- **Data de Criação:** 2026-10-03
- **Origem:** Engenheiro Chefe Humano no chat, revisando a resposta de segurança da REQ-097 do `conn2flow-site`.
## Pedido do Humano
> "Uma coisa que você pode fazer é um handshake tanto do distribuído quanto do central. Mesmo que fuja a chave, tem que ser obrigatoriamente o [REDACTED] identificado. O central quer iniciar uma conexão, manda uma requisição; o [REDACTED]ído faz uma conexão perguntando: esse aqui é você mesmo? [...] Aí depois, quando os dois têm essas duas conferências, mesmo que sumam com a chave de segurança de comunicação, não consegue acessar a rede. Ou então me explica o que pode ser melhor que isso." Trocas periódicas de chave: "ok".
## Problema
Hoje cada requisição do canal é assinada com o segredo da instalação (HMAC, carimbo de tempo, nonce). Quem obtiver esse segredo fala pelo Central com o site do cliente, ou pelo cliente com o Central, de qualquer lugar.
## Escopo
1. **Confirmação de origem.** Quem quer falar (A) cria um desafio de uso único (60 s) e pede a abertura (`abrir`). Quem recebe (B) não confia no pedido: liga de volta para o endereço que **ele** tem cadastrado para A (`central-url` no cliente; `url` do cadastro no Central) e pergunta se o desafio é de A (`confirmar`). Só com o "sim" de A, B abre a sessão.
2. **Chave de sessão.** B devolve uma chave de sessão aleatória (cifrada para A), válida por 15 minutos. Toda requisição comum passa a ser assinada com ela (`X-C2F-Session`); o segredo da instalação só serve para abrir sessão. A chave de trabalho é trocada sozinha a cada 15 minutos.
3. **Exigência no receptor.** Com a confirmação ligada (padrão do `config.php`, `MODULO_DISTRIBUIDO_ORIGIN_CHECK`), requisição sem sessão válida é recusada (401). Sessão de outra instalação é recusada.
4. **Retomada.** Sessão recusada (401, antes de executar qualquer coisa) é reaberta e a requisição repetida uma vez.
5. Testes de unidade com as duas pontas simuladas, incluindo o ataque com a chave roubada.
## Critérios de aceite
- CA-1: com o segredo da instalação, mas fora do endereço cadastrado, não se abre sessão em nenhuma das direções.
- CA-2: requisição comum sem sessão, com sessão vencida, forjada ou de outra instalação é recusada.
- CA-3: painel, troca de login, estado da conta, rotinas e webhooks seguem funcionando no Lab (roteiros dos módulos distribuídos).
- CA-4: com `MODULO_DISTRIBUIDO_ORIGIN_CHECK=false` o canal volta ao modo anterior (compatibilidade durante a publicação).
## Fora do escopo
- Chaves assimétricas (Ed25519) e TLS mútuo: propostos como próximo passo no relatório.
- Rotação automática do segredo da instalação (continua manual no [REDACTED] do site).