Proveniência & segurança: fail-closed por padrão

Um sistema que ingere logs de chat privado, raspa a web e grava arquivos que um agente nomeia precisa ser paranoico por construção — não por lembrar de checar. A ADR-0011 define quatro restrições permanentes — fail-closed em tudo, redação de PII antes de um byte sair da máquina, isolamento de um corpus de prompts vazado e uma regra de clean-room — e elas não são slogans: aparecem como guardas reais no código que você já conheceu. Esta lição conecta a política à implementação: a fronteira Zod, a defesa realpath/path-traversal no SkillStore, o fail-closed DEFAULT_TIER = T4, e a redação de PII antes da chamada de modelo.

01 · O único princípio: a porta trancada por padrão

Antes das quatro restrições, entenda a ideia que as une — porque todas são a mesma ideia vista de ângulos diferentes. Pense numa porta: ela pode ter dois padrões. Ou está destrancada e você tranca o que sabe ser perigoso (fail-open), ou está trancada e só abre para quem você reconheceu explicitamente (fail-closed). O Alembic escolhe a segunda em tudo relevante à segurança.

Por que isso é tão poderoso? Porque segurança por omissão é frágil — basta esquecer de bloquear um caso e o sistema vaza. Segurança por negação padrão é robusta: o caso que você nunca imaginou já está barrado, porque tudo que não foi explicitamente permitido é negado. Guarde essa frase; ela reaparece em cada uma das quatro restrições e em cada SVG abaixo.

02 · As quatro restrições permanentes

A ADR-0011 não é uma lista de boas intenções: cada restrição aponta para um lugar concreto no código. Veja as quatro de uma vez, depois desça em cada uma.

A restrição 1 lista quatro mecanismos concretos — guardas realpath, webhooks HMAC, comparações de tempo constante e Zod em toda fronteira. O último é o mais onipresente: todo subsistema do motor faz safeParse da entrada antes de tocá-la, e o resultado é binário — ou um valor tipado válido, ou um err. Dado externo nunca entra no sistema sem passar por essa porta.

03 · Restrição 1 no código: a guarda de path-traversal

Você viu o SkillStore na Lição 12. Sua espinha de segurança é validateSupportPath — uma função pura que recusa qualquer caminho relativo que pudesse escapar do diretório da skill. Ela espelha o has_traversal_component + _resolve_skill_target do Hermes (confinado a ALLOWED_SUBDIRS) e é o validador fail-closed de manual: lista o que permite (via SKILL_SUPPORT_DIRS / isSupportDir) e nega todo o resto.

// packages/hermes/src/skills/skill-store.ts:404-433 (condensado)
const validateSupportPath = (relPath: string): Result<string, Error> => {
  if (relPath.length === 0) return err(new Error('file path is required.'));
  if (relPath.includes('\\')) return err(…'use forward slashes.');   // sem truques de backslash
  if (relPath.startsWith('/')) return err(…'must be relative.');     // sem caminhos absolutos

  const segments = relPath.split('/').filter((s) => s.length > 0);
  for (const segment of segments) {
    if (segment === '..' || segment === '.')                         // sem segmentos de traversal
      return err(…'path traversal is not allowed.');
  }
  const first = segments[0];
  if (first === undefined || !isSupportDir(first))                  // deve ser um subdir PERMITIDO
    return err(…'first segment must be one of …');
  return ok(normalized);   // só agora: um caminho relativo vetado e confinado
};

Note a forma: todo ramo é uma negação exceto o ok final. Um ../../etc/passwd controlado por atacante é rejeitado na checagem de ..; um sorrateiro references/../../secret também é rejeitado. A função é pura e nunca lança, então compõe limpa no mundo Result — falhas de segurança surgem como erros tipados, fail-closed (ADR-0011 §1, "não passes silenciosos"). Há ainda uma quinta guarda no source: segments.length < 2 rejeita um nome solto sem subdir (deve ser references/api.md, não só api.md).

Outra forma de ver a mesma função é como uma esteira de peneiras em série: o caminho só chega ao fim se passar, em ordem, por cinco peneiras — e cada uma só sabe negar. Não há atalho nem caminho lateral.

04 · Anatomia de uma função fail-closed (fluxograma)

A melhor maneira de "ver" o fail-closed é seguir um caminho hostil pela função. Cada losango é uma checagem; cada "SIM" para uma checagem de perigo leva direto à negação. Só sobreviver a todos os losangos chega no ok. Siga o ataque references/../secret pelas setas — ele morre no losango do ...

Repare no que o fluxograma não tem: nenhuma seta que diga "se eu não reconheci o problema, deixa passar". Não há saída fail-open. A única forma de chegar ao ok é sobreviver a todas as negações — o caminho feliz é o caminho mais estreito, e é de propósito.

05 · Restrição 1, de novo: fail-closed por tier padrão

A expressão mais profunda de fail-closed não é uma guarda que você chama — é o padrão. DEFAULT_TIER = T4 significa que qualquer trabalho não explicitamente classificado como autônomo é estacionado, esperando um humano (Lição 24; a própria ADR-0011 aponta isso para a ADR-0004). A linha real é minúscula e definitiva:

// packages/contracts/src/tier.ts:51,63
export const DEFAULT_TIER: Tier = Tier.T4;            // o desconhecido estaciona
export const isParked = (tier: Tier): boolean =>       // e "estacionado" é checável
  tier === DEFAULT_TIER;

A ADR-0011 traça a linha ela mesma: "o caso desconhecido nega, nunca permite (é também por isso que DEFAULT_TIER = T4)". Autonomia não classificada é impossível por construção, não por lembrar de checar. Compare as duas mentalidades:

06 · Restrição 2: PII antes de egressar, não antes de emitir

A palavra sutil é egressar. Seria fácil redar PII só antes de mostrar um resultado a um usuário. A ADR-0011 exige mais: um Signal derivado de um canal privado (WhatsApp, Discord, Skool, Circle) é "redado de PII antes de sair da máquina local — antes da chamada de modelo, não meramente antes de emitir". O modelo de ameaça assume que o próprio endpoint do modelo está fora da fronteira de confiança, então dado privado bruto nunca pode estar num payload de requisição.

Onde está, no código, esse "antes de egressar"? Em packages/etl/src/pii.ts. O módulo é puro e determinístico — a mesma entrada sempre produz a mesma saída redada, então é trivialmente testável e seguro de chamar em qualquer ponto do funil. Ele detecta e mascara quatro tipos de PII, e a tabela de máscaras é literal:

07 · A guarda de egresso, no código real

A redação por si só não basta — algo precisa impedir que um sinal privado não-redado escape. Essa é a função assertRedactedForEmit: um portão fail-closed que só deixa passar um sinal de canal privado se ele já provou ter passado pela redação. Repare que ela nunca lança — retorna um err tipado (EmitBlocked), no estilo Result do motor inteiro.

// packages/etl/src/pii.ts:178-192 (condensado)
export const assertRedactedForEmit = (
  signal: BusinessSignal | RedactedSignal,
  channel: string,
): Result<RedactedSignal | BusinessSignal, EmitBlocked> => {
  const alreadyRedacted = 'redacted' in signal && signal.redacted === true;
  if (alreadyRedacted) return ok(signal);                 // já provou redação → passa
  if (!isPrivateChannel(channel)) return ok(signal …);      // canal público → passa
  return err({                                          // privado + não redado → NEGA
    kind: 'private_unredacted',
    channel, signalId: plain.id,
    message: `signal … from private channel '…' must be redacted before emit`,
  });
};

Leia a lógica como três portas: (1) se o sinal carrega a prova redacted: true, passa; (2) se o canal é público, passa (canais públicos não exigem redação forçada); (3) caso contrário — privado e sem prova de redação — nega com um erro tipado. O tipo RedactedSignal tem o campo redacted: true literal: você não consegue forjar a prova sem passar por redactSignal. A segurança está no tipo, não na boa vontade do chamador.

A frase "a segurança está no tipo" merece um diagrama. redacted: true não é um booleano que você seta à mão — é um tipo literal que só existe como saída de redactSignal. Não há outro caminho para fabricar a prova; o compilador é o segurança.

08 · Decida na mão: esse sinal pode egressar? (passo a passo → agora você)

Você viu a guarda. Agora rode-a na cabeça, devagar, sobre um caso concreto — depois um caso é seu. Recuperar o procedimento (não só ler o veredito) é o que fixa.

09 · Restrições 3 & 4: não siga dados, não copie source

As duas últimas são sobre disciplina, não checagens em runtime. Isolamento CL4R1T4S: um corpus vazado de prompts de vendor (e seu README de payload de injeção) "é isolado e nunca ingerido como instrução; é dado para analisar, nunca um comando a seguir". É defesa contra prompt-injection na camada de ingestão — o corpus é texto inerte, nunca executado.

Clean-room do tac: o tac é um blueprint de licença educacional, então "seus padrões são reimplementados do zero, com zero código ou prompts literais, e seu source nunca é publicado". A fusão inteira do @alembic/hermes é uma reimplementação TypeScript do zero precisamente por causa dessa regra — que é também por que as lições citam o source do próprio Alembic, nunca o Python do Hermes.

10 · Proveniência amarra tudo

Tudo nesta lição assenta sobre um único desenho: onde fica a fronteira de confiança. Dentro dela está a sua máquina local; fora dela estão o endpoint do modelo, a rede e o dado de terceiros (raspado, vazado, ingerido). Cada uma das quatro restrições é uma guarda exatamente no ponto em que algo cruza essa fronteira — e cada cruzamento é fail-closed.

11 · Fail-open vs fail-closed: o trade-off lado a lado

Toda a lição gira em torno de uma escolha de postura: o que acontece com o caso desconhecido. A tabela mostra os números/comportamentos; o gráfico abaixo torna o trade-off visível — fail-open é "produtivo" até o primeiro caso esquecido virar um vazamento.

12 · A confusão central: "antes de emitir" vs "antes de egressar"

Se você guardar uma única distinção desta lição, que seja esta — e ela é geométrica. Numa linha do tempo do dado, "egressar" (sair da máquina) acontece antes de "emitir" (mostrar o resultado final). A chamada de modelo já é um egresso. Redar só no fim deixaria PII bruto viajar pela rede.

Confusões comuns

13 · Como isso se encaixa

A postura desta lição não é uma feature isolada — é uma casca de guardas em volta do funil de destilação (Lição 15). Olhe a peça inteira: dado bruto entra a montante (alguma parte vinda da web e de mídia); o funil destila; e em cada ponto onde algo cruza a fronteira de confiança há um portão fail-closed. A redação de PII antes de egressar guarda a saída para o endpoint do modelo; a guarda de path-traversal guarda a entrada de skills no SkillStore; o fail-closed por tier (DEFAULT_TIER = T4) é a postura por baixo de tudo. As demais peças da metodologia ou alimentam dado que esta casca filtra, ou dependem de que ela já filtrou.

As peças que se conectam a esta

A postura de segurança toca cinco outras lições — cada uma abre uma peça que aqui aparece como uma aresta guardada:

14 · Na prática

Chega de teoria — prove as guardas. A casca de segurança é, antes de tudo, código testado: a redação de PII e o portão de egresso vivem em packages/etl/src/pii.ts, e a suíte pii.test.ts fixa cada ramo fail-closed. A guarda de path-traversal vive em outro pacote (@alembic/hermes), então tem sua própria suíte. Rode as duas:

# 1) A redação de PII + o portão de egresso (packages/etl/src/pii.ts)
$ pnpm --filter @alembic/etl test

# 2) A guarda de path-traversal do SkillStore (packages/hermes/src/skills/skill-store.ts)
$ pnpm --filter @alembic/hermes test

# saída esperada (forma ilustrativa — as contagens dependem da build):
#   ✓ src/pii.test.ts  (redactText masks every supported PII kind)
#   ✓ src/pii.test.ts  (assertRedactedForEmit blocks an unredacted
#                       private-channel signal — fail-closed err)
#   ✓ src/skills/skill-store.test.ts  (rejects a ".." escape in the relative path)
#   ✓ src/skills/skill-store.test.ts  (rejects a file outside the allowed support subdirs)
#   Test Files  passed

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.