gif

## Visão geral GIF (Governed Intelligence Framework) é um runtime de governança para invocação de ferramentas de IA. Em vez de registrar o que um agente fez após o fato, ele impõe políticas antes de qualquer ferramenta ser executada, na camada MCP (Model Context Protocol). O projeto enquadra o problema como um de trajetórias em vez de registros: um único agente pode emitir milhares de consultas individualmente permitidas em fontes de dados não relacionadas em segundos, e a inferência extraída do agregado pode ser, ela própria, uma violação que os padrões de governança em nível de registro não capturam. ## O que ele faz Quando um agente de IA invoca uma ferramenta, o GIF: 1. Verifica a Persona — se a identidade de governança está ativa, dentro de sua janela de validade e autorizada a chamar a ferramenta. 2. Impõe escopo — chamadas fora do escopo declarado da Persona são rejeitadas e registradas como eventos de governança de primeira classe, em vez de erros comuns. 3. Avalia políticas de combinação — os manipuladores de ferramentas do adotante chamam um avaliador fornecido pelo GIF antes da execução; se o conjunto de fontes de dados acessadas na sessão atual ultrapassar um limite de sensibilidade declarado, a chamada que completa essa combinação é bloqueada. O exemplo do README: registros financeiros, registros de RH e metadados de comunicações podem ser permitidos isoladamente, mas sua junção entre chamadas separadas pode não ser. 4. Registra tudo — chamadas permitidas, rejeições e sessões, com permissões somente INSERT no nível do banco de dados. ## Conceitos-chave - **Persona**: uma identidade de governança que carrega um propósito declarado obrigatório e não anulável, escopo explícito de ferramentas, limites de validade temporal e uma cadeia de delegação. Criada por administradores humanos antes da ação da IA. - **Escopo**: uma lista enumerada de ações permitidas; ferramentas fora dela não podem ser chamadas. - **Violação de escopo**: um registro de governança de primeira classe, descrito como evidência de que o limite funcionou. - **Política de combinação**: uma regra declarada de que um conjunto específico de fontes de dados acessadas em conjunto em uma sessão constitui um limite. O GIF fornece o esquema, um avaliador de políticas ativas e semântica de falha fechada. O avaliador v0.1 usa resolução de política por primeira correspondência; a avaliação exaustiva está listada como um item de trajetória v0.2. - **Trilha de auditoria**: somente INSERT no nível de permissão do banco de dados — a função da aplicação não pode executar UPDATE ou DELETE nos registros de auditoria. - **Cadeia de delegação**: Personas filhas possuem subconjuntos estritos do escopo da Persona pai, de modo que as ações de subagentes rastreiam de volta à autoridade administrativa raiz. ## Arquitetura Dois contêineres Docker: PostgreSQL 16 e um servidor MCP Node.js. Os clientes fazem POST no servidor MCP, que valida a Persona, impõe o escopo e despacha a ferramenta; o PostgreSQL armazena personas, sessões, audit_events e scope_violations. O avaliador de políticas de combinação é exposto como uma primitiva que os servidores de ferramentas adotantes invocam em seus próprios pontos de despacho. O motor de imposição é distribuído como um pacote importável (`gif-enforcement`), registrado como uma dependência git versionada, para que os adotantes possam adicionar ferramentas de domínio sem modificar o código-fonte do GIF. ## Integridade da auditoria Os registros de auditoria são encadeados por hash na camada do banco de dados: um gatilho calcula um resumo SHA-256 sobre uma forma canônica de bytes e o vincula ao resumo da linha anterior, de modo que a mutação ou exclusão posterior quebra a cadeia. Uma CLI verificadora percorre partições, recalcula os resumos e relata incompatibilidades e quebras de cadeia. A forma canônica e o procedimento de verificação são especificados em um repositório separado de Contrato de Registro de Auditoria à Prova de Violação (forma canônica `audit-record-contract/1`, originalmente submetido ao MCP como SEP-3004), para o qual o GIF é a implementação de referência. Um conjunto de vetores espelhado vive no repositório; o README afirma que `npm run vectors` espera 26 vetores passando. ## Início rápido Os pré-requisitos são Docker Engine 24+, Docker Compose v2 e Git. O fluxo documentado clona a tag `v0.2.4`, copia `.env.example` removendo o segredo placeholder, anexa um `IDENTITY_HMAC_SECRET` gerado, define senhas reais e executa `docker compose up -d --build`. O banco de dados inicializa funções, esquema e migrações automaticamente. O servidor MCP se recusa a iniciar se o segredo HMAC permanecer como placeholder ou tiver menos de 32 bytes. Ambas as portas publicadas vinculam-se a `127.0.0.1` por padrão; `GIF_BIND_ADDR` amplia isso, e um runbook de implantação em produção é referenciado. O endpoint MCP valida o cabeçalho `Origin` do navegador, respondendo 403 para origens não permitidas, a menos que listadas em `GIF_ALLOWED_ORIGINS`; clientes que não enviam cabeçalho Origin não são afetados. A saúde é verificada via `GET /health`. ## Estado atual O README recomenda fixar `v0.2.4`, que roda sobre o substrato MCP SDK 2.0 e carrega a semântica de sessão de governança v0.2: handles `gif_session_id` explícitos emitidos por `session_start`, fechamento conduzido pelo chamador e TTL de relógio de parede. A imposição central é descrita como completa e validada de ponta a ponta contra uma instância real do PostgreSQL 16, com uma suíte de integração e cenários de conformidade executados em cada commit via CI, e modo estrito do TypeScript em todo o código. As capacidades distribuídas listadas incluem ciclo de vida de persona, a camada de imposição MCP com transporte HTTP Streamable, a trilha de auditoria somente anexação encadeada por hash com uma CLI verificadora de cadeia, detecção de violação de escopo, imposição de cadeia de delegação, gerenciamento de sessões, registro de ferramentas e despacho conduzido por registro, empacotamento de imposição, a primitiva de política de combinação e vinculação de identidade do provisionador via token de identidade HMAC. Um release legado `v0.1.0` sobre o substrato aposentado MCP SDK v1 não é mais recomendado: ele carece de endurecimento de identificadores SQL (advisory GHSA-47gp-w74f-grvr) e não recebe backports. O README afirma que a injeção afeta tags até e incluindo `v0.2.0-rc.1`, com `v0.2.0-rc.2` sendo a primeira tag corrigida, e aponta os adotantes existentes para um documento de migração. Um roteiro de endurecimento de conformidade cobrindo âncoras de carimbo de tempo externas, criptografia em repouso, endurecimento operacional multi-inquilino e cadeias de auditoria por escopo está documentado na visão geral do produto. ## Documentação e licença O repositório inclui um guia em linguagem simples, uma visão geral do produto, um passo a passo da base de código, diagramas de arquitetura, um documento de segredos, runbooks para contribuidores e adotantes, e vetores de conformidade executáveis. Licenciado sob Apache License 2.0; copyright 2026 Notboatanchor Labs LLC.