Pular para o conteúdo

Referência

Fronteira de confiança e procedência do estado

Veja o que um valor do repositório clonado pode decidir e o que cada máquina precisa confirmar.

O que vem do clone não decide execução

Rodar o Orkastery num repositório de terceiros não executa código só por isso. Um valor vindo do clone não vira opção de processo, não vira executável e não vira caminho fora da raiz; os únicos comandos executados por desenho são os declarados.

A fronteira de confiança é a auditoria de cada chamada de processo e de cada caminho que o núcleo monta com dado do clone, com a classe de cada um e sem roteiro de exploração. A matriz completa, módulo por módulo, fica na fonte.

Na versão 0.6.10, entram as correções da auditoria e as regras de procedência do estado, estas como patch de segurança, por decisão do dono.

Em que o núcleo confia

A linha de comando é de quem está no teclado: merece confiança, mas é validada quando vai ao git, como --remoto, --para, --de e os ids de thread. O ambiente e as pastas da conta (~/.orkastery, ~/.claude e ~/.codex) também são confiáveis.

Não merecem confiança o manifesto e o setup versionados (orkastery.yaml e orkastery.setup.json), o estado versionado no clone (.orkastery e os bundles .ork-ci/<thread>.json), as branches de estado (ork/roadmap-reservas, a da fábrica e as ork/*) e o que chega de outra máquina da rede (retratos, reservas e o frontmatter do roadmap). Saída de ferramenta (git, runtime) é dado, nunca código.

Cada chamada de processo e cada caminho da matriz recebem uma destas classes. Toda chamada de processo do núcleo usa vetor de argumentos, sem shell; shell só existe nos comandos declarados e na sonda de sandbox do MCP.

  • Declarado: comando que o manifesto ou a claim declara para rodar. É o produto (reexecutar o que se alega), e o SECURITY.md documenta.
  • Inerte: só constantes, ou dado confiável.
  • Defendido: dado externo, mas validado, depois de --end-of-options, com a ref qualificada ou com o sha conferido.
  • Corrigido: era injeção de opção, executável escolhido pelo clone ou caminho fora da raiz.
  • Corrigido em decisão do dono: fecha um pendente mudando comportamento, e o dono escolheu mesclar como patch de segurança.
  • Pendente do dono: fechar exige mudar comportamento documentado ou aceito hoje, e a decisão é do dono.

Comandos declarados

São os únicos que o núcleo executa por desenho, e o SECURITY.md lista todos. A documentação não promete aviso em tempo de execução: trate o orkastery.yaml e o estado de um repositório de terceiros como um Makefile.

ork doctor, ork board, ork thread list, ork init, ork thread new e ork retry plan não executam comando declarado.

  • verify.build, verify.test, verify.typecheck e verify.preparo, na worktree, por ork verify, ork fix open, ork fix reverify, ork retry run (na ação corrigir-dirigido), a baseline do ork phase run e o gate do ork ship.
  • ci.command e o bundle .ork-ci/<thread>.json, no ork ci run do runner do CI.
  • As claims (o claims.jsonl e o --verificar) e o doneWhen do thread.json, nos mesmos comandos do verify; o ork claims add só as roda com a policy do manifesto.
  • As correções do GO-FIX e as claims dos achados de auditoria (board.jsonl), no ork fix reverify e na conferência da rodada de auditoria.
  • O binário do runtime (claude e codex), pelos adaptadores, no ork phase run e no ork retry run.
ork verify <thread>
ork fix reverify <thread>
ork audit verify <rodada>
ork ci run --branch <branch>

As cinco regras de procedência

Na versão 0.6.10, cinco regras (P1 a P5) fecham os pendentes que a auditoria deixou com o dono. A ideia é a mesma em todas: o que vem com o repositório não decide executável, caminho fora da raiz nem publicação desta máquina; quando o uso é legítimo, a máquina confirma fora do git, e a recusa é tipada e diz o comando.

  • Postura do sandbox (P1): o runtime.sandbox que dá ao agente acesso total (danger-full-access) só despacha pelo Codex depois de ork setup sandbox confirmar <postura>, gravado em .orkastery/private/postura-local.json (0600, fora do git, só para este checkout). Sem isso, ork phase run e ork retry run recusam com runtime.sandbox-nao-confirmado, e o ork doctor acusa.
  • Estado rastreado (P2): estado versionado do .orkastery não escolhe cwd, worktree nem executável (estado.rastreado). O cwd vindo do thread.json, do ledger ou da fila, para o agente ou para o git, só vale na raiz do projeto ou numa worktree que o repositório registrou (estado.worktree-nao-registrada). Vale para despacho, retomada, verify, claims, GO-FIX, prova do GO, handoff, liveness, ork ci prepare, ork worktree audit e ork worktree release.
  • Transporte do pulse e do digest (P2): só valem o pulse-host.json e o master-host.json locais, arquivos comuns fora do índice do git (transporte.rastreado).
  • Ponteiros do recall e do handoff (P2): o ork recall, o ork handoff recall e o ork handoff export só leem arquivo que, pelo caminho real, fica na raiz do projeto ou na worktree registrada da thread. O recall recusa com ponteiro.fora-da-raiz, e o export deixa de apontar para fora.
  • Pasta das worktrees (P3): o worktree.dir que leva para fora da raiz pelo caminho real (caminho absoluto, subida de pasta, link no caminho ou .git) só cria worktree depois de ork setup worktree confirmar, gravado em .orkastery/private/worktree-local.json (0600, fora do git, só para este checkout e esta pasta). Sem isso, a criação recusa com worktree.dir-fora-da-raiz, e o ork doctor acusa. As worktrees que já existem seguem valendo, e o MCP segue recusando worktree fora da raiz.
  • Eval (P4): o ork eval só executa o catálogo (cenários de comportamento, hooks e core/dist) do pacote que está rodando. Um diretório com as pastas skills, references e eval achado a partir do cwd que não é o do pacote recusa com eval.catalogo-alheio, e a mensagem diz como rodar de propósito o eval daquele checkout. O CI do kit, com node core/dist/index.js eval na raiz, não muda.
  • Fábrica compartilhada (P5): o fabrica.compartilhada: true do manifesto não liga mais a publicação do retrato desta máquina (threads, nome e host) no remoto do clone, nem a leitura das outras máquinas. Só a adesão da máquina liga: ork fabrica entrar, em ~/.orkastery/maquina.json, ou ORK_FABRICA_COMPARTILHADA=1. Com o pedido no manifesto e sem a adesão, o ork doctor e o ork fabrica avisam com fabrica.nao-confirmada.
ork setup sandbox confirmar danger-full-access
ork setup worktree confirmar
ork fabrica entrar
ork doctor
git rm -r --cached .orkastery

O que a auditoria corrigiu

Na versão 0.6.10, a auditoria corrige estes casos sem mudar comportamento aceito:

  • O mergeSha e a branch de destino de um ship_done do ledger só chegam ao git log da detecção de reversão como sha hexadecimal e nome de branch, depois de --end-of-options; antes, um ledger versionado no clone passava uma opção ao git, em ork master e ork ship.
  • ork docs sincronizar não cai mais na base crua do manifesto quando ela não resolve, e, do sha do ledger e do commit do frontmatter, só sha hexadecimal chega ao git.
  • O manifesto recusa worktree.base_branch que não vale como nome de branch no git (começa com hífen ou tem .. no nome).
  • O manifesto recusa memory.cli relativo: vale nome procurado no PATH, como orkmind, ou caminho absoluto. A sonda do OrkMind, inclusive a do ork doctor, ignora entradas relativas do PATH e shebang com interpretador relativo, e o ork brain roda o executável com cwd no $HOME, não na raiz do clone.
  • .orkastery, .orkastery/threads e a pasta de uma thread como link simbólico recusam com estado.link, e o append do ledger, das claims e do board usa O_NOFOLLOW; antes, um link versionado levava a escrita para fora da raiz.
  • O id de uma rodada de auditoria lido do run.json precisa ser um nome simples (audit.rodada-invalida).
  • O SECURITY.md passa a listar todos os comandos declarados, inclusive verify.preparo, ci.command, os bundles .ork-ci/<thread>.json e o doneWhen.

Barreira de dado privado e DSN fora do ambiente

Na versão 0.6.10, a barreira de dado privado é um comando do núcleo: ork privado varrer procura caminho de home, e-mail fora da lista permitida, hostname no formato de máquina e os termos da lista local, que fica fora do git. As exceções em orkastery.privado.json exigem padrão e valor exato, sem curinga, com caminho apenas como filtro e motivo obrigatório. O relatório diz arquivo, linha, coluna e padrão, nunca o valor, e mascara o nome do arquivo com achado.

Com a policy dado_privado no manifesto, o ork verify varre o diff da thread e reprova com policy.violation em block, e o ork ci prepare recusa gerar o bundle com achado. No CI do núcleo, a varredura é um passo do job documentacao. A lista local só é lida como arquivo comum do usuário atual, sem link e com permissão 0600; ausente, como no CI, só os padrões genéricos rodam, e a saída diz isso.

A DSN da memória ganha uma fonte fora do ambiente dos agentes: memory.database_url_file aponta para ~/.orkastery/segredos/<nome>, e o manifesto não escolhe arquivo fora dessa pasta. As duas fontes são exclusivas, então o ork nunca cai de uma para a outra. Antes de abrir, o núcleo confere pelo lstat cada pasta entre a casa e a pasta de segredos, abre com O_NOFOLLOW e exige arquivo comum, do usuário que roda o ork, com permissão 0600 ou 0400 exata, até 4 KiB e uma linha só com a DSN.

A resposta do processo filho que repita a DSN ou a senha dela é recusada inteira, com memory.transport.secret, brain.transport.secret ou brain.migration.secret, sem o valor. O limite é honesto e está dito: o agente roda com o mesmo usuário do dono e pode ler um arquivo 0600 dele. O ganho é a senha fora de env, da transcrição e do contexto do modelo; isolamento forte pede outro usuário ou um intermediário.

ork privado varrer
ork privado varrer --base origin/main
ork memory status

O que segue com o dono

A auditoria deixou seis itens como pendentes do dono, porque fechá-los mudava comportamento aceito ou documentado. Os cinco primeiros, P1 a P5, ganharam as regras de procedência desta página, mescladas por decisão do dono. A P6 segue pendente.

Na mesma lista, ficam registrados, com risco baixo:

  • ork retry run --dry-run, na ação corrigir-dirigido, reexecuta claims e verify: são comandos declarados, mas contra a semântica do --dry-run.
  • O perfil do runtime gravado no ledger escolhe o CLAUDE_CONFIG_DIR e o CODEX_HOME de comandos de consulta.
  • A P6: o memory.cli do manifesto pode ser qualquer nome do PATH ou caminho absoluto, inclusive dentro do clone, e o memory.database_url_env nomeia qualquer variável de ambiente. O valor vai ao executável do Brain em toda consulta, e a fonte de arquivo memory.database_url_file só aceita a pasta de segredos do ork, para não alargar a classe.
  • O ci.external_repositories aceita segmento de subida de pasta no caminho de uma leitura pela API do GitHub.
  • O ork adapter install ainda acha o catálogo a partir do projeto, como o ork eval achava, mas só copia o adaptador para dentro do próprio projeto e prefere o executável do PATH quando ele existe.

Para quem contribui com o núcleo

As regras para o código em core/src:

  • Valor do clone a caminho do git: valide antes da chamada com remotoValido ou exigirRemoto, branchValida ou shaValido (core/src/branch-de-estado.ts), e ponha --end-of-options antes dele.
  • A ref de branch vai qualificada, e o merge vai pelo sha conferido, nunca pelo nome.
  • O executável nunca sai do manifesto por caminho relativo, e o cwd de um executável escolhido por configuração não é a raiz do clone.
  • Caminho com id vindo de arquivo tem um segmento só, conferido por regex, e o diretório de estado não é link.
  • Append em estado usa O_NOFOLLOW; escrita de arquivo inteiro vai por um temporário criado com wx e depois renomeado.
  • Caminho lido de ponteiro guardado no estado é conferido pelo caminho real com exigirCaminhoContido (core/src/procedencia.ts). Decisão que o manifesto não pode tomar sozinho vira confirmação local em .orkastery/private, com lerArquivoPrivado e gravarArquivoPrivado (core/src/postura-local.ts).
  • O teste da correção reprova o código anterior; os de referência são core/test/fronteira-de-confianca.test.ts, core/test/procedencia-e-postura.test.ts e core/test/fronteira-pendentes.test.ts.