@fontdata/ai-harness 4.6.0 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,83 @@
1
+ # Segurança: comandos destrutivos e arquivos sensíveis
2
+
3
+ Os hooks do harness leem o texto de cada comando e o caminho de cada gravação antes de rodar. Eles não são uma
4
+ fronteira de segurança completa: são uma rede contra o erro comum, inclusive com 2 ou 3 sessões em paralelo no mesmo
5
+ repositório.
6
+
7
+ ## Camadas
8
+
9
+ | Camada | O que faz |
10
+ |---|---|
11
+ | Hook `comando-destrutivo` (`Bash`/`PowerShell`) | nega o catastrófico e pede aprovação para o destrutivo legítimo |
12
+ | Hook `arquivo-sensivel` (`Edit`/`Write`/`MultiEdit`/`NotebookEdit`) | nega e pergunta conforme o caminho gravado |
13
+ | `permissions.deny` do `.claude/settings.json` | `git push --force` e a leitura de segredos pela ferramenta `Read` |
14
+ | Aprovação humana | o dev decide quando o hook pergunta; a documentação do Claude Code garante a aprovação no modo `auto`, mas não diz nada sobre `bypassPermissions` e `acceptEdits` |
15
+ | Sandbox do Claude Code | recomendado; o harness não o ativa |
16
+
17
+ ## O que nega
18
+
19
+ - Apagar recursivo com alvo na raiz do disco, `/`, `~`, `$HOME`, `%USERPROFILE%`, caminho com variável, nome curto
20
+ 8.3 (`USUARI~1`) ou `/c/` do Git Bash.
21
+ - Formatar ou limpar disco (`Format-Volume`, `diskpart`, `format X:`, `mkfs`, `dd of=/dev/…`, `cipher /w`).
22
+ - Texto jogado num interpretador de shell: `… | sh`, `… | iex`, `bash -c "$(…)"`, `eval "$(…)"`, `-EncodedCommand`.
23
+ - Enviar arquivo de segredo para fora (`curl -d @`, `-F …=@`, `-T`, `scp`, `rsync`).
24
+ - Gravar em `.git/`, `~/.ssh/`, `~/.aws/`, `~/.config/gh/`, `~/.gnupg/` e no `.ai-harness/lock.json`.
25
+
26
+ ## O que pergunta
27
+
28
+ - Apagar recursivo (`rm -r`, `find -delete`, `xargs rm`, `rimraf`, `Remove-Item -Recurse`, `rd /s`…). Passa direto
29
+ só `rm`, `rimraf`, `Remove-Item`, `rd` e `del` cujos alvos são caminhos relativos simples terminados numa pasta de
30
+ `seguranca.pastas_descartaveis` (`dist`, `./dist/`, `packages/a/dist`; não `dist/*` nem `../dist`).
31
+ - Git que descarta mudança: `reset --hard`, `clean -f`, `checkout -- <caminho>`, `checkout .`, `restore` sem
32
+ `--staged`, `stash drop`/`clear`, `branch -D`, `push --delete`.
33
+ - `git add -A`, `git add .` e `git commit -a` com dois ou mais trabalhos ativos: passe os caminhos da task.
34
+ - DDL/DML ou arquivo `.sql` por `psql`, `mysql`, `mariadb`, `sqlite3`, `sqlcmd` ou `isql`; `SELECT` passa.
35
+ - Ler arquivo de segredo pelo terminal (`cat`, `Get-Content`, `source`…).
36
+ - Gravar nos arquivos que configuram a proteção (`.ai-harness/config.json`, `.claude/settings*.json`,
37
+ `~/.claude/settings*.json`) e fora da raiz. Fora da raiz passam sem pergunta as pastas temporárias (`os.tmpdir()`,
38
+ `/tmp`, `/private/tmp`) e o resto de `~/.claude/` (memória, planos).
39
+
40
+ ## Leitura de segredos: `Read` × terminal
41
+
42
+ - Pela ferramenta `Read`, só os nomes listados em `permissions.deny` são negados (`**/.env`, `**/.env.local`,
43
+ `**/.env.production`, `*.pem`, `*.key`, `~/.ssh/**`…). Um `.env.qa` fica legível: quem usa outros nomes os
44
+ acrescenta ao `permissions.deny`.
45
+ - Pelo terminal, todo `.env*` secreto pede aprovação; `.env.example`, `.env.sample`, `.env.template` e `.env.dist`
46
+ passam.
47
+
48
+ ## Conduta quando bloqueado
49
+
50
+ - Negado: não rode. Mostre ao usuário o comando exato ou os caminhos exatos e peça que ele rode, se quiser, com
51
+ `! <comando>` no prompt.
52
+ - Pergunta: espere a decisão do usuário; recusa é resposta final.
53
+ - Nunca tente um comando equivalente que contorne a regra (outro binário, script, `node -e`, variável, caminho
54
+ reescrito). Se a regra parece errada, diga isso ao usuário.
55
+
56
+ ## Consultar antes
57
+
58
+ ```bash
59
+ npx @fontdata/ai-harness checar-comando "<comando>"
60
+ ```
61
+
62
+ Responde `NEGADO` (saída 2), `PERGUNTA` (3) ou `LIBERADO` (0), com a regra e o motivo, sem gravar nada no projeto.
63
+
64
+ ## Configuração
65
+
66
+ Seção `seguranca` do `.ai-harness/config.json`:
67
+
68
+ | Chave | Padrão | Efeito |
69
+ |---|---|---|
70
+ | `pastas_descartaveis` | `node_modules`, `dist`, `build`, `out`, `coverage`, `.next`, `.turbo`, `.cache`, `.vite`, `tmp`, `temp`, `__history`, `__recovery` | lista que substitui a padrão |
71
+ | `negar_leitura_segredos` | `true` | com `false`, o `update` remove os denys de leitura e o terminal deixa de perguntar |
72
+ | `desligar_bypass` | `false` | com `true`, o `update` grava `permissions.disableBypassPermissionsMode: "disable"` |
73
+
74
+ Voltar `desligar_bypass` a `false` não remove a chave: apague `disableBypassPermissionsMode` do
75
+ `.claude/settings.json` à mão. Mudanças nos denys entram com `npx @fontdata/ai-harness update --yes`.
76
+
77
+ Saída de emergência: o modo `"aviso"`. Se o hook travar comandos válidos (inclusive por erro interno), ponha
78
+ `hooks.comando-destrutivo` ou `hooks.arquivo-sensivel` em `"aviso"` no `.ai-harness/config.json`: ele só avisa até a
79
+ correção. Com `"desligado"`, o hook continua registrado, mas libera tudo sem avisar.
80
+
81
+ ## Crédito
82
+
83
+ Inspirado no `no-wipe` (github.com/matheusbattisti/no-wipe, licença MIT), reimplementado nos padrões do harness.