dsh-guard-messenger

Usa o teu próprio DeepSeek Harness pelo celular — a Web UI inteira, para codificar de verdade — sem nunca alargar o bind para fora do loopback: o túnel termina em 127.0.0.1 (acesso local abre direto), e pelo túnel só entra quem tem a chave no link ?key= (que o bot envia) — ligas e desligas o acesso pelo Telegram.

Instalação (uma linha)

dsh plugin --profile web add dsh-guard-messenger

Instalação pelo link do repositório

dsh plugin add github:frederico-kluser/dsh-guard-messenger

Funciona sem allowBuilds e sem build no install: os artefactos compilados
(dist/, lib/) vêm commitados no git e os hooks prepare/prepack foram
removidos de propósito — o pnpm 11 bloqueia build de dependências git
(ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED), que era exactamente o que impedia o
install-by-link.

> Nota de release: o comando só funciona depois de este ramo estar pushado
> no GitHub. Enquanto o repositório servir a árvore antiga (a que ainda tinha
> prepare), o pnpm add github:… falha com
> ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED.

> Instalação por tarball: os artefactos compilados (lib/client.js e
> dist/) vêm commitados no repositório (o que faz o install-by-link
> funcionar sem allowBuilds) e prepublishOnly continua como hook de release.
> Sem esses artefactos a ativação do client lançaria MissingClientBundleError.
> Ver docs/PANEL-TELEGRAM.md.

Modelo de ameaça, em 5 linhas — antes de qualquer feature

> Este plugin expõe, por escolha, um agente que executa código na tua máquina. Antes de continuares, lê isto:
>
> 1. O TLS termina na borda da Cloudflare. O texto claro (prompts, código, respostas) passa por um terceiro — é o que permite WAF/Access/cache. Não é ponta-a-ponta.
> 2. A URL do túnel é pública e não é segredo. Quem protege é a chave ?key= no link, não a obscuridade do endereço.
> 3. Cloudflare Access não pode ficar na frente de um quick tunnel. Sobre *.trycloudflare.com toda a autenticação tem de estar dentro da aplicação.
> 4. O quick tunnel não tem SLA — é "intended for testing and development only".
> 5. Isto não é "seguro por padrão sem pensar". Reduzimos a superfície, autenticámos a borda por chave/sessão e demos-te o botão de desligar; não eliminámos a categoria do risco.
>
> Detalhe e o que cada mitigação faz: docs/THREAT-MODEL.md.

Modelo de segurança (o que o código garante de facto)

Leitura honesta das garantias — cada linha aponta para o código que a cumpre; nada aqui é
"seguro por padrão sem pensar", é redução de superfície e autenticação.

O projeto foi construído para travar o DSH em loopback. Este plugin também o expõe pela internet. Parece contradição — e a formulação honesta é esta:

> O bind continua em 127.0.0.1 e o DSH aí abre direto (sem login). O que muda é que passa a existir um processo filho supervisionado (cloudflared) que leva o tráfego da borda da Cloudflare até um proxy dedicado que autentica na borda (sessão ou ?key=). Não é o mesmo que --host 0.0.0.0: o socket local nunca é alargado, a exposição é opt-in, efémera e revogável em um comando — e quem proteger /api, o fallback da SPA e o handshake de WebSocket é esse proxy, não o loopback.
>
> O que não muda: a superfície de ataque lógica cresce. Antes, um atacante precisava de acesso à máquina; agora, pelo túnel, precisa da chave no link (ou de uma sessão roubada). Trocámos "inalcançável" por "alcançável e autenticado na borda" — sem login, sem senha a digitar. Essa troca é reversível a qualquer momento pelo botão de desligar (na aba "Remote Access" das settings do DSH, ou /desligar no bot; a chave, pelo /rotacionar).

Quem não aceitar esta troca deve usar Tailscale ou SSH — e dizemo-lo com mais calma em docs/TUNNEL.md e na secção "Quando NÃO usar" abaixo.

O que faz (e porquê)

1. Protege o túnel, não o loopback. O DSH abre direto em 127.0.0.1 (sem login); quem expõe é um proxy dedicado que autentica tudo o que chega da internet — /api, o fallback da SPA e o handshake de WebSocket. Recusa endereços de bind fora do loopback no carregamento e recusa permissões proibidas (danger-full-access). Resolve a superfície da discussão upstream #853.
2. Nunca pede senha a ninguém. O acesso pelo túnel entra por sessão ou pela chave no link ?key= (CSPRNG, 256 bits, digest em disco). A chave é reutilizável até /rotacionar (que gera chave nova, invalida sessões e encerra ativamente as conexões já abertas — quem tiver o link antigo cai na hora, incluindo WebSockets) ou derrubar o túnel. O 401 é sem desafio de login — não há prompt nem formulário de login.
3. Suba um túnel efémero para acederes pelo celular, com TTL que o derruba sozinho e um probe fail-closed que impede um túnel "nu" (sem proxy autenticado atrás).
4. Ligar/desligar pelo Telegram ou pela aba "Remote Access" das settings do DSH — o botão de matar na mão.
5. Dispara agentes do harness pelo bot — com uma skill da allowlist e um prompt, o dono manda um subagente do DeepSeek Harness trabalhar na própria máquina (/agente), acompanha os runs (/agentes) e cancela (/parar-agente). O dispatch executa código no host: exige confirmação em duas etapas, e o agente corre com as permissões do harness — nunca com o token do bot. Manual completo: docs/AGENTS.md.

Bot e túnel: a aba "Remote Access" das settings do DSH

O controle do bot e do túnel vive DENTRO da UI do DSH — na aba "Remote Access"
do modal de settings (o plugin registra-se no slot settings.section; não há
bloco injetado na home). A aba traz o chip de estado do bot OFFLINE/ONLINE
fiel ao runtime, o formulário de token, o pareamento pelo painel, a privacidade e
o cartão "Túnel" — estado ao vivo (desligado/ligando/online/instável/
desligando/falhou), a URL quando READY, o countdown "expira em", as tentativas
e os botões Ligar túnel (confirmação em duas etapas), Desligar túnel
(confirmação) e Repor (após falha) (duas etapas, só quando falhou).

O botão "Ver instruções" ("Como ligar o bot") pede ao servidor os passos do
provedor ativo:
- OFFLINE → as instruções de conexão (Telegram: criar o bot no @BotFather),
dsh-guard-setup --pedir-token, --parear, enviar /parear; quem
segue esse passo a passo de facto coloca o bot online;
- ONLINE → dicas de uso.

Depois de pareado (docs/ONBOARDING-TELEGRAM.md), os comandos de controlo do bot:

O link enviado no /ligar é
https:///?key=: a chave no link autentica o túnel, é
reutilizável até rotacionar (ou derrubar o túnel) e, ao ser válida, é trocada
por uma sessão e o navegador é redirecionado para a URL limpa (sem ?key=).
Nunca se pede uma senha a digitar — o acesso é por sessão ou por chave no
link, e o acesso local abre direto.

> Porque a chave pode aparecer no chat (e é esperado): o ?key= é o mecanismo
> de autenticação e o bot é o canal de entrega. É a chave do link, não uma
> "senha permanente" — não há senha a digitar para acesso.

Cada promessa destas aponta para a linha de código que a cumpre: ver docs/ARCHITECTURE.md.

Agentes: disparar skills do harness pelo bot

O dispatcher de agentes (docs/AGENTS.md — manual completo) liga o bot ao
ctx.subagents do harness: o dono escolhe uma skill da allowlist e escreve um
prompt, o host spawna um subagente in-process (sessão fresca, zero contexto
do pai) que trabalha na própria máquina, e o resultado chega ao chat.

Porquê tanta cerimónia: o dispatch executa código na tua máquina. É a ação
que mais AUMENTA a exposição do bot — por isso exige confirmação em duas etapas
(nonce do host, como /ligar). E o agente disparado corre com as permissões do
harness e nunca recebe o token do bot nem credencial nenhuma deste plugin
(S3): o request carrega só a skill renderizada no bloco ` canónico + o texto do teu prompt. Os runs são **efémeros por desenho**: vivem só em memória — um reinício do DSH cancela tudo (disposeem LIFO) e a lista recomeça vazia. Sem allowlist declarada (config.agents.skills`), nenhum agente é
disparável — fail-closed por construção.

Tarefas: chats e worktrees do harness pelo bot

Os comandos de tarefa criam coisas reais no harness: /novo-chat e
/novo-chat-wt abrem sessões do DSH com o prompt submetido (o chat corre de
verdade), e /worktree cria uma worktree git isolada — branch
guard/ em -worktrees/, irmã do checkout — sem nunca
destruir nada que exista. /status-tarefa mostra o detalhe de um run com as
métricas reais do harness (tokens, tempos, turnos); o que o host não mediu
aparece como —, nunca como número inventado.

Exemplos reais:

/worktree fix-guard-regex
/novo-chat-wt fix-guard-regex corrige o teste que falha em test/security/host-header.test.ts
/novo-chat resume o estado do repositório e diz o próximo passo
/agentes
/status-tarefa 01J8ZC2A

Os ids de 8 caracteres aparecem em /agentes (que lista agentes, chats e
worktrees com a métrica resumida de cada um). Como /agente, o /novo-chat e o
/novo-chat-wt executam código e o /worktree altera a máquina — todos
pedem confirmação em 2 etapas: os chats mostram o prompt exato que vai
correr, e o /worktree mostra o nome (e a base, quando indicada). Textos
exatos e arquitetura:
docs/AGENTS.md e docs/ux/01-CONTRATO-BOT.md.

Provedores de mensageria

O worker do bot é neutro ao provedor: o núcleo (roteador, allowlist, pareamento, outbox)
vive em worker/surface/** e cada canal vive isolado no seu adaptador:
worker/providers/telegram/** (única carga de grammY). O boot lê o provedor ativo por DSH_GUARD_PROVIDER
(config.worker.provider, default telegram); o token é TELEGRAM_BOT_TOKEN no Telegram —
o secrets.env guarda a linha do provedor ativo e dsh-guard-setup
sabe qual é a do provedor ativo.

Adicionar um provedor novo (WhatsApp, Matrix…) é implementar o contrato neutro
ProviderAdapter e registá-lo no registry. O manual completo — arquitetura, contrato tipo-a-tipo,
a tabela de provedores com os limites de cada um e o checklist passo-a-passo para um provedor
novo — está em docs/PROVIDERS.md, e as habilidades de apoio (skills) em
.agents/skills/dsh-provider-bot e .agents/skills/dsh-telegram-provider.

Como flui um pedido (arquitetura em 8 linhas)

Telemóvel (navegador)
│  abre o link que o bot enviou: https:////?key=   (a chave viaja em query)
▼
❨ Cloudflare edge ❩   TLS → HTTP/2 → WebSocket ; o TLS termina AQUI (texto claro passa pela borda)
▼
cloudflared — quick tunnel (conexão de saída apenas, sem conta, sem SLA)
▼  http://127.0.0.1:3080   (o túnel termina no loopback; o socket local NÃO é alargado)
plugin (proxy dedicado — só o túnel passa por aqui)
│  autentica na borda: sessão (cookie) ou `?key=` válida → troca por sessão (302 p/ URL limpa)
│  403 origem/ Host fora da allowlist · 401 SEM desafio (sem login) · 200 com sessão
▼
DeepSeek Harness Web UI — bind travado em 127.0.0.1 (nunca 0.0.0.0)

O que o diagrama esconde e é decisivo: o acesso local abre direto (sem barreira) — a autenticação vive só no proxy do túnel. A chave no link é gerada pela máquina (CSPRNG, 256 bits), guardada em disco só como digest, reutilizável até rotacionar, e a ?key= viaja em query (visível a intermediários) — trade assumido do modelo expose-port. A recusa de bind fora do loopback acontece no carregamento, com falha ruidosa — ver o mapa de módulos em docs/ARCHITECTURE.md.

Quickstart (5 comandos)

# 1. instala o plugin (uma linha; ativa o manifesto de Bundle automaticamente)
dsh plugin --profile web add dsh-guard-messenger

# 2. corre o DSH — o acesso local abre direto (sem login)
dsh web

# 3. (opcional) liga o bot: dsh-guard-setup + /parear (docs/ONBOARDING-TELEGRAM.md);
#    depois, no bot,
#    /ligar envia o link com a chave ?key=

# 4. confirma que o acesso local abre (o DSH responde direto); a borda sem chave
#    dá 401 — ver docs/INSTALL.md Passo 3
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3080/

# 5. para desligar/desinstalar
dsh plugin remove dsh-guard-messenger

examples/minimal é um exemplo mínimo instalável com o critério de aceite documentado (local abre direto / borda sem ?key= dá 401 / 200 com o link ou sessão / nenhum processo no fim).

Quando NÃO usar isto

• Time / multiusuário. É um plugin de dono único: uma allowlist de userKey/chatKey do Telegram (ids numéricos, nunca usernames) e a chave do link. Não há RBAC nem auditoria multi-tenant.
• Produção / uptime. O quick tunnel é, nas palavras da própria Cloudflare, "intended for testing and development only" e "We don't guarantee any SLA or uptime".
• Quem precisa de compliance. O TLS termina na borda da Cloudflare; o texto claro passa por lá. Não é E2E.
• Quem quer "seguro por padrão sem pensar". Isto não existe aqui. Estás a expor um agente com shell; o plugin reduz superfície e entrega o kill switch, não elimina a categoria.
• Máquina corporativa. trycloudflare.com tem reputação de malware documentada e muitas redes/EDRs bloqueiam ou sinalizam cloudflared.

Alternativas (comparação honesta)

Nenhuma alternativa é apresentada como ruim; várias são melhores em vários eixos. O valor está na combinação, não em vencer item a item.

Em suma: isto não é "mais um túnel" — é o fluxo completo de um dono só (onboarding → chave no link → túnel efémero → link no celular → botão de desligar), com o bind travado em loopback e o acesso local aberto, sem login.

Compatibilidade

Faixa suportada do upstream @deepseek-ai/dsh: 0.1.0-rc.7 .. 0.1.1-rc.1 (política N/N-1). A tabela completa — versão do plugin × faixa de rc × status — está em docs/COMPATIBILITY.md, que é gerado de dsh-compat.yml (nunca editado à mão).

> Atenção ao registry: a tag latest dos subpacotes @deepseek-ai/dsh-* aponta para a publicação mais antiga, não para a mais recente. Fixa a versão explicitamente.

Validação end-to-end (o que a suíte prova de verdade)

Matriz de alto nível a partir das suítes reais do repo — test/e2e/**, test/security/**, test/integration/**
— referidas por ficheiro. São verificações que o CI corre, não promessas; o detalhe de cada nível e como correr
está em docs/TESTING.md.

Honestidade sobre o que esta matriz não é: o e2e usa um fake-cloudflared e uma borda
falsa — nenhum byte sai de 127.0.0.1 no CI, por construção. A re-confirmação através da borda
e da rede reais é a suíte test/live/** (DSH_GUARD_LIVE_TESTS=1), opt-in e fora do gate —
ver docs/TESTING.md §5.

Desinstalar e reverter

dsh plugin remove dsh-guard-messenger

Deixa zero processos remanescentes e a Web UI volta ao comportamento original. Para apagar também a chave do link, o pareamento e o estado local: remove ~/.dsh/guarded-bot. Detalhe em docs/INSTALL.md.

Docs

• docs/INSTALL.md — instalação passo a passo
• docs/ONBOARDING-TELEGRAM.md — conectar o bot do Telegram e parear
• docs/AGENTS.md — o dispatcher de agentes: config, comandos, segurança e limites
• docs/EXPOSURE.md — o que muda quando o túnel sobe
• docs/TUNNEL.md — quick vs named, TTL, modelo de ameaça do transporte
• docs/THREAT-MODEL.md — atacante, mitigação, o que não mitiga
• docs/TROUBLESHOOTING.md — sintoma → causa → o que fazer
• docs/ARCHITECTURE.md — costuras Cordis e mapa de módulos
• docs/TESTING.md — como rodar cada nível de teste

Contribuir e reportar

• Encontraste uma vulnerabilidade? Não abras issue pública. Lê SECURITY.md e usa o canal privado lá descrito (Private Vulnerability Reporting ou e-mail).
• Queres contribuir? CONTRIBUTING.md tem o ambiente em quatro comandos, os níveis de teste, o que nunca é aceite num PR e como adicionar um provedor de mensageria.
• Código de conduta: CODE_OF_CONDUCT.md.

Licença MIT — LICENSE. O DeepSeek Harness a montante também é MIT.